thetadatadx 13.0.0

package/streaming-session.js

@@ -0,0 +1,789 @@
+/**
+ * `await using session = await client.streaming(callback)` (TC39 explicit
+ * resource management) wrapper for the Client FPSS streaming
+ * lifecycle.
+ *
+ * On `[Symbol.asyncDispose]`, `stopStreaming()` is called and then the
+ * async ring-drain barrier `awaitDrain(5000)` is awaited, so the
+ * streaming consumer thread has stopped and enqueues no further events
+ * before the JS callback closure is released. This mirrors the C++ RAII
+ * destructor in `thetadatadx-cpp/src/thetadatadx.cpp`.
+ *
+ * Delivery caveat (napi-specific, differs from Python/C++): the per-event
+ * callback runs on the Node main thread, delivered through a bounded
+ * threadsafe-function queue that sits DOWNSTREAM of the consumer thread.
+ * `awaitDrain` waits on the consumer thread, not on that delivery queue,
+ * so a bounded backlog of already-queued events can still invoke the
+ * callback on later event-loop turns AFTER the disposer resolves. napi
+ * delivers that backlog in throttled bursts across event-loop turns, so
+ * no finite wait in this wrapper can guarantee it has fully flushed. In
+ * the Python and C++ bindings the callback runs on the consumer thread
+ * itself, so their barrier is exact; here it is not. Do not release state
+ * the callback dereferences at scope exit assuming zero further
+ * invocations -- guard the callback to no-op after teardown if a late
+ * invocation against freed state would be unsafe.
+ *
+ * Every public method on `Client` (subscribe_*,
+ * unsubscribe_*, activeSubscriptions, droppedEventCount, reconnect,
+ * ...) is reachable on the session via a `Proxy` `get` trap. There is
+ * no hand-listed mirror of subscription methods here -- adding a new
+ * method to the napi-rs `Client` makes it callable through the
+ * session automatically, with zero drift surface.
+ *
+ * Loaded as the package's CommonJS entry point (`main` in
+ * `package.json`) so consumers get the wrapper when they
+ * `require('thetadatadx')`. The native loader in `index.js` is
+ * auto-generated by napi-rs and re-exported untouched.
+ */
+
+'use strict';
+
+const native = require('./index.js');
+const { wrapStreamViewBatches } = require('./record_batch_forwarder.js');
+
+// ── Typed error hierarchy ─────────────────────────────────────────────
+//
+// The Rust napi binding (`to_napi_err` in `thetadatadx-ts/src/lib.rs`)
+// surfaces every `thetadatadx::Error` as a `napi::Error` whose
+// `reason` carries a `[ClassName] ...` prefix. The JS interceptor
+// below parses that prefix and re-throws the matching subclass so
+// callers can write `catch (e) { if (e instanceof thetadatadx.SubscriptionError)
+// { ... } }` rather than substring-matching the message.
+//
+// The canonical leaf set (`NotFoundError`, `DeadlineExceededError`,
+// `UnavailableError`, `InvalidParameterError`, ...) is identical to the
+// Python, C++, and C ABI leaf sets, so a `catch` clause ports across
+// bindings by class name. Python additionally ships two back-compat
+// aliases (`NoDataFoundError` / `TimeoutError`) that do not exist here.
+//
+// A rate limit carrying a server back-off hint widens the prefix to
+// `[RateLimitError retry_after_ms=N] ...`; the interceptor parses the
+// hint off and seats it as a `retryAfter` (seconds) property on the
+// thrown `RateLimitError`.
+
+class ThetaDataError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ThetaDataError';
+  }
+}
+class AuthenticationError extends ThetaDataError {
+  constructor(message) {
+    super(message);
+    this.name = 'AuthenticationError';
+  }
+}
+class InvalidCredentialsError extends AuthenticationError {
+  constructor(message) {
+    super(message);
+    this.name = 'InvalidCredentialsError';
+  }
+}
+class SubscriptionError extends ThetaDataError {
+  constructor(message) {
+    super(message);
+    this.name = 'SubscriptionError';
+  }
+}
+class RateLimitError extends ThetaDataError {
+  constructor(message) {
+    super(message);
+    this.name = 'RateLimitError';
+    // Server-supplied minimum back-off in seconds, parsed from the
+    // upstream `google.rpc.RetryInfo` hint, or `null` when none was
+    // supplied. Always present so callers can read it unconditionally.
+    this.retryAfter = null;
+  }
+}
+class InvalidParameterError extends ThetaDataError {
+  constructor(message) {
+    super(message);
+    this.name = 'InvalidParameterError';
+  }
+}
+class NotFoundError extends ThetaDataError {
+  constructor(message) {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+class DeadlineExceededError extends ThetaDataError {
+  constructor(message) {
+    super(message);
+    this.name = 'DeadlineExceededError';
+  }
+}
+class UnavailableError extends ThetaDataError {
+  constructor(message) {
+    super(message);
+    this.name = 'UnavailableError';
+  }
+}
+class NetworkError extends ThetaDataError {
+  constructor(message) {
+    super(message);
+    this.name = 'NetworkError';
+  }
+}
+class SchemaMismatchError extends ThetaDataError {
+  constructor(message) {
+    super(message);
+    this.name = 'SchemaMismatchError';
+  }
+}
+class StreamError extends ThetaDataError {
+  constructor(message) {
+    super(message);
+    this.name = 'StreamError';
+  }
+}
+class ConfigError extends ThetaDataError {
+  constructor(message) {
+    super(message);
+    this.name = 'ConfigError';
+  }
+}
+
+const CLASS_BY_NAME = {
+  ThetaDataError,
+  AuthenticationError,
+  InvalidCredentialsError,
+  SubscriptionError,
+  RateLimitError,
+  InvalidParameterError,
+  NotFoundError,
+  DeadlineExceededError,
+  UnavailableError,
+  NetworkError,
+  SchemaMismatchError,
+  StreamError,
+  ConfigError,
+};
+
+// `[ClassName] message` or `[ClassName retry_after_ms=N] message`. The
+// optional `retry_after_ms` group carries the rate-limit back-off hint
+// the Rust shim widens the prefix with; it is parsed off and surfaced
+// as `retryAfter` (seconds) on the thrown `RateLimitError`.
+const PREFIX_RE = /^\[([A-Za-z]+Error)(?:\s+retry_after_ms=(\d+))?\]\s*(.*)$/s;
+
+/**
+ * Re-cast a napi-thrown `Error` as the matching typed subclass when
+ * the reason carries the `[ClassName] ...` prefix the Rust shim
+ * emits. Anything that doesn't match the prefix surfaces unchanged
+ * — preserves the existing `Error` shape for failures from the
+ * generic napi machinery (e.g. argument coercion failures inside
+ * the bindings).
+ */
+function rethrowTyped(err) {
+  if (!(err instanceof Error) || typeof err.message !== 'string') {
+    throw err;
+  }
+  const match = PREFIX_RE.exec(err.message);
+  if (!match) {
+    throw err;
+  }
+  const [, className, retryAfterMs, payload] = match;
+  const Cls = CLASS_BY_NAME[className];
+  if (!Cls) {
+    throw err;
+  }
+  const typed = new Cls(payload);
+  // Seat the rate-limit back-off (ms → seconds) when the prefix carried
+  // a `retry_after_ms` hint, so callers can read `err.retryAfter`.
+  if (retryAfterMs !== undefined && typed instanceof RateLimitError) {
+    typed.retryAfter = Number(retryAfterMs) / 1000;
+  }
+  // Preserve the stack from the napi-thrown Error so the typed
+  // re-throw still carries the original call site.
+  typed.stack = err.stack;
+  throw typed;
+}
+
+// Drain timeout applied on `[Symbol.asyncDispose]`. Matches the C++
+// destructor's 5 s budget in `thetadatadx-cpp/src/thetadatadx.cpp` and the FFI
+// free-path budget in `thetadatadx-ffi/src/streaming.rs::FREE_DRAIN_TIMEOUT`.
+// Cross-binding parity matters more than tunability here -- a slow
+// JS callback that needs more than 5 s to drain is already a contract
+// violation worth surfacing.
+const EXIT_DRAIN_TIMEOUT_MS = 5000;
+
+// Wrapper-defined member names. Lookups for these resolve on the
+// session itself; everything else proxies to the underlying
+// `Client`. Symbol.asyncDispose is included so `await using`
+// finds the wrapper's dispose, not anything on the native binding.
+const WRAPPER_OWN = new Set(['_client', 'constructor']);
+
+function isClosedClientError(err) {
+  return err instanceof Error && /client is closed/.test(err.message);
+}
+
+function closedClientError() {
+  return new StreamError(
+    'client is closed; construct a new client to make further calls',
+  );
+}
+
+// apache-arrow is loaded lazily so it is only required by callers that
+// actually consume the columnar `batches()` reader. The per-tick
+// `*ToArrowIpc` exports likewise hand back raw IPC buffers and leave the
+// apache-arrow decode to the caller; the reader decodes here so the user
+// sees native apache-arrow `RecordBatch` values straight from `for await`.
+let _arrow = null;
+function loadArrow() {
+  if (_arrow === null) {
+    try {
+      // eslint-disable-next-line global-require
+      _arrow = require('apache-arrow');
+    } catch (e) {
+      throw new Error(
+        "the streaming `batches()` reader decodes Arrow IPC with apache-arrow; " +
+          "install it as a peer dependency (`npm install apache-arrow`). " +
+          `Underlying error: ${e && e.message ? e.message : e}`,
+      );
+    }
+  }
+  return _arrow;
+}
+
+/**
+ * Pull-based columnar reader over the live stream — a sibling to the
+ * per-event `startStreaming(callback)`.
+ *
+ * `for await (const batch of reader)` yields apache-arrow `RecordBatch`
+ * values under a fixed schema (concatenate them freely). The reader is an
+ * `AsyncIterable` and a TC39 async-disposable: `await using reader = ...`
+ * closes it (unsubscribe + tear down) on scope exit, or call `close()`.
+ *
+ * Wraps the native `RecordBatchStreamHandle`, which crosses the napi
+ * boundary as Arrow IPC buffers; this class decodes each with
+ * `apache-arrow.tableFromIPC` so the public `RecordBatch` type is the
+ * native apache-arrow one.
+ */
+class RecordBatchStream {
+  constructor(handle) {
+    this._handle = handle;
+    this._schema = undefined;
+  }
+
+  /**
+   * The fixed Arrow schema every yielded batch carries, as an
+   * apache-arrow `Schema`. Decoded once from the schema-only IPC buffer.
+   */
+  get schema() {
+    if (this._schema === undefined) {
+      const arrow = loadArrow();
+      const ipc = this._handle.schemaIpc();
+      // A schema-only IPC stream decodes to a zero-batch Table whose
+      // `.schema` is the fixed schema.
+      this._schema = arrow.tableFromIPC(ipc).schema;
+    }
+    return this._schema;
+  }
+
+  /** Batches dropped so far under the `dropOldest` policy; `0` under `block`. */
+  get dropped() {
+    return this._handle.dropped;
+  }
+
+  /**
+   * Close the reader: unsubscribe and tear the FPSS session down.
+   * Idempotent; further iteration ends.
+   */
+  close() {
+    this._handle.close();
+  }
+
+  async *[Symbol.asyncIterator]() {
+    const arrow = loadArrow();
+    try {
+      for (;;) {
+        // eslint-disable-next-line no-await-in-loop
+        const ipc = await this._handle.nextIpc();
+        if (ipc === null || ipc === undefined) {
+          return;
+        }
+        // One batch per IPC buffer (the reader writes exactly one). Decode
+        // to a Table and yield its single RecordBatch.
+        const table = arrow.tableFromIPC(ipc);
+        for (const batch of table.batches) {
+          yield batch;
+        }
+      }
+    } finally {
+      // Iteration ended (consumed, broke out, or threw): release the
+      // session deterministically, mirroring the `await using` dispose.
+      this._handle.close();
+    }
+  }
+
+  async [Symbol.asyncDispose]() {
+    this._handle.close();
+  }
+}
+
+/**
+ * The `client.stream` view, or `null` when the client is closed. A closed
+ * client throws on the `stream` getter ("client is closed"); every caller here
+ * treats that single `null` sentinel as "no streaming surface" so operating on
+ * a closed client stays a no-op rather than throwing, matching the base
+ * client's asyncDispose guard.
+ *
+ * @param {InstanceType<typeof native.Client>} client
+ * @returns {any}
+ */
+function streamOrNull(client) {
+  try {
+    return client.stream;
+  } catch {
+    return null;
+  }
+}
+
+function streamOrClosed(client) {
+  try {
+    return { stream: client.stream, closed: false };
+  } catch (err) {
+    if (isClosedClientError(err)) {
+      return { stream: null, closed: true };
+    }
+    return { stream: null, closed: false };
+  }
+}
+
+/**
+ * Resolve the object that carries the streaming lifecycle methods
+ * (`stopStreaming` / `awaitDrain`) for either client kind, or null when
+ * there is nothing live to tear down.
+ *
+ * The unified `Client` exposes streaming under a `.stream` sub-view; the
+ * standalone `StreamingClient` IS the streaming surface, with the same
+ * methods directly on it. `streamOrNull` alone returns `undefined` for a
+ * standalone client (it has no `.stream`), which is why the session disposer
+ * used to silently tear nothing down while the standalone stream kept
+ * running. This resolver returns the `.stream` view for a unified client and
+ * the client itself for a standalone one.
+ *
+ * @param {any} client
+ * @returns {any}
+ */
+function streamSurface(client) {
+  const view = streamOrNull(client);
+  if (view) return view;
+  // Standalone StreamingClient: the lifecycle methods live on the client.
+  if (
+    client &&
+    typeof client.stopStreaming === 'function' &&
+    typeof client.awaitDrain === 'function'
+  ) {
+    return client;
+  }
+  return null;
+}
+
+class StreamingSession {
+  /**
+   * Construct a session bound to a `Client` instance. Returns a
+   * Proxy that forwards every unknown attribute access to the
+   * underlying instance, so adding a `subscribe_X` method to the napi
+   * binding makes it callable through the session with no drift.
+   *
+   * @param {InstanceType<typeof native.Client>} client
+   * @returns {StreamingSession}
+   */
+  constructor(client) {
+    this._client = client;
+    return new Proxy(this, {
+      get(target, prop, receiver) {
+        // Wrapper-defined members (Symbol.asyncDispose, _client,
+        // constructor) take precedence; everything else forwards to
+        // the underlying Client instance.
+        if (WRAPPER_OWN.has(prop) || prop === Symbol.asyncDispose) {
+          return Reflect.get(target, prop, receiver);
+        }
+        const client = target._client;
+        // The unified client's streaming surface (subscribe, diagnostics,
+        // lifecycle) moved onto the `client.stream` sub-namespace view.
+        // Resolve a name there first so `session.subscribe(...)` and
+        // `session.activeSubscriptions()` keep working, then fall back to
+        // the methods that stay on `Client` (e.g. `sessionUuid`,
+        // `subscriptionInfo`, `activeFullSubscriptions`).
+        const { stream, closed } = streamOrClosed(client);
+        if (stream && prop in stream) {
+          const value = stream[prop];
+          return typeof value === 'function' ? value.bind(stream) : value;
+        }
+        if (!(prop in client) && closed && typeof prop === 'string') {
+          throw closedClientError();
+        }
+        const value = client[prop];
+        // Bind methods to the underlying instance so `this` resolves
+        // correctly when the caller invokes them.
+        return typeof value === 'function' ? value.bind(client) : value;
+      },
+      has(target, prop) {
+        if (WRAPPER_OWN.has(prop) || prop === Symbol.asyncDispose) return true;
+        const client = target._client;
+        const stream = streamOrNull(client);
+        return (stream && prop in stream) || prop in client;
+      },
+    });
+  }
+
+  /**
+   * TC39 explicit resource management: invoked by `await using session
+   * = ...` on scope exit. Stops the streaming connection and awaits the
+   * ring-drain barrier so the consumer thread has stopped and enqueues no
+   * further events before the JS closure is released. Mirrors the C++
+   * RAII destructor.
+   *
+   * NOT an exact "no callback after this resolves" barrier on the napi
+   * delivery path: already-queued events can still invoke the callback on
+   * later event-loop turns after this resolves (see the module-level
+   * delivery caveat). Python and C++ fire on the consumer thread, so their
+   * barrier is exact; this one covers the consumer thread only.
+   *
+   * Drain timeout failures fire `console.warn` rather than throwing;
+   * the streaming pipeline is already torn down (`stopStreaming` ran),
+   * and the drain barrier is best-effort observability. Throwing here
+   * would mask any error from the `using` block body.
+   *
+   * @returns {Promise<void>}
+   */
+  async [Symbol.asyncDispose]() {
+    // Disposing a closed client is a no-op: the `stream` getter throws once
+    // `close()` has run, and there is nothing left to drain. `streamSurface`
+    // resolves both the unified client (`.stream` view) and the standalone
+    // `StreamingClient` (methods on the client itself) so a session wrapping a
+    // standalone client actually tears the stream down instead of leaking it.
+    const stream = streamSurface(this._client);
+    if (!stream) return;
+    stream.stopStreaming();
+    const drained = await stream.awaitDrain(EXIT_DRAIN_TIMEOUT_MS);
+    if (!drained) {
+      console.warn(
+        `Client streaming drain timed out after ${EXIT_DRAIN_TIMEOUT_MS}ms; ` +
+          'consumer callback may still be firing. The JS callback closure ' +
+          'will remain referenced until the consumer exits.',
+      );
+    }
+  }
+}
+
+// Monkey-patch `streaming(callback)` onto the napi-generated
+// `Client` class. Returning a `Promise<StreamingSession>` matches
+// the spec example (`await using session = await client.streaming(cb)`)
+// and leaves room for an async startup path in the future without an
+// API break.
+if (
+  native.Client &&
+  typeof native.Client.prototype.streaming !== 'function'
+) {
+  native.Client.prototype.streaming = async function streaming(callback) {
+    // Await the handshake: startStreaming is async, so a connect/auth
+    // failure must reject this Promise (and reach the caller's typed
+    // catch) rather than escape as an unhandled rejection, and the
+    // session must not be handed back before the stream is live.
+    await this.stream.startStreaming(callback);
+    return new StreamingSession(this);
+  };
+}
+
+// The same `streaming(callback)` factory on the standalone `StreamingClient`,
+// which has no `.stream` sub-view — its lifecycle methods live directly on the
+// client. Without this a standalone-client user could not open a context-managed
+// `await using session = await streamingClient.streaming(cb)` session at all, so
+// the `StreamingSession` disposer (now resolving the standalone surface via
+// `streamSurface`) had nothing to attach to. Matches the Python standalone
+// client's `streaming(...)` helper.
+if (
+  native.StreamingClient &&
+  typeof native.StreamingClient.prototype.streaming !== 'function'
+) {
+  native.StreamingClient.prototype.streaming = async function streaming(callback) {
+    await this.startStreaming(callback);
+    return new StreamingSession(this);
+  };
+}
+
+// TC39 explicit resource management on the base clients. `close()` is the
+// napi-generated deterministic teardown; these computed-symbol members cannot
+// be emitted by napi-rs (it names only identifier methods), so they are patched
+// on here — the same wrapper-side pattern as `streaming()` and the
+// `StreamingSession` disposers. `[Symbol.dispose]` backs `using client = ...`
+// (sync scope exit); `[Symbol.asyncDispose]` backs `await using client = ...`
+// and additionally awaits the streaming drain barrier so a callback closure is
+// safe to release, warning (never throwing) on timeout to match the session.
+for (const Klass of [native.Client, native.MarketDataClient]) {
+  if (!Klass) continue;
+  if (typeof Klass.prototype[Symbol.dispose] !== 'function') {
+    Klass.prototype[Symbol.dispose] = function dispose() {
+      this.close();
+    };
+  }
+  if (typeof Klass.prototype[Symbol.asyncDispose] !== 'function') {
+    Klass.prototype[Symbol.asyncDispose] = async function asyncDispose() {
+      // `stream` exists only on the unified `Client`; the market-data-only
+      // client has no streaming surface, so `close()` alone is the teardown.
+      // An already-closed client throws on the `stream` getter ("client is
+      // closed"); treat that as nothing-to-drain so disposing a closed client
+      // stays a no-op rather than rejecting.
+      let stream;
+      try {
+        stream = this.stream;
+      } catch {
+        stream = undefined;
+      }
+      if (stream) {
+        // Await the ring-drain barrier first so the consumer thread has
+        // stopped and enqueues no further events before the JS closure is
+        // released; warn (never throw) on timeout to match the context-managed
+        // session. This covers the consumer thread only: already-queued events
+        // may still invoke the callback on later event-loop turns after this
+        // resolves (see the module-level delivery caveat).
+        stream.stopStreaming();
+        const drained = await stream.awaitDrain(EXIT_DRAIN_TIMEOUT_MS);
+        if (!drained) {
+          console.warn(
+            `Client close drain timed out after ${EXIT_DRAIN_TIMEOUT_MS}ms; ` +
+              'the streaming consumer callback may still be firing.',
+          );
+        }
+      }
+      // Always run the deterministic close: it releases the registered
+      // callback back to V8 and is the single teardown the sync disposer also
+      // routes through. Skipping it would leak the callback reference on the
+      // `await using` path. Idempotent after the stop above.
+      this.close();
+    };
+  }
+}
+
+// TC39 explicit resource management on the standalone `StreamingClient`, whose
+// terminal teardown is `stopStreaming()` (it has no separate `close()`; the
+// stop clears the callback and retires the session). `[Symbol.dispose]` backs
+// `using sc = StreamingClient.connect(...)`; `[Symbol.asyncDispose]` additionally
+// awaits the ring-drain barrier (consumer thread stopped, no further events
+// enqueued) before release, warning (never throwing) on timeout to match the
+// unified client and the session. As on the other disposers this covers the
+// consumer thread only -- already-queued events may still invoke the callback
+// on later event-loop turns after it resolves (see the module-level caveat).
+if (native.StreamingClient) {
+  const Klass = native.StreamingClient;
+  if (typeof Klass.prototype[Symbol.dispose] !== 'function') {
+    Klass.prototype[Symbol.dispose] = function dispose() {
+      this.stopStreaming();
+    };
+  }
+  if (typeof Klass.prototype[Symbol.asyncDispose] !== 'function') {
+    Klass.prototype[Symbol.asyncDispose] = async function asyncDispose() {
+      this.stopStreaming();
+      const drained = await this.awaitDrain(EXIT_DRAIN_TIMEOUT_MS);
+      if (!drained) {
+        console.warn(
+          `StreamingClient drain timed out after ${EXIT_DRAIN_TIMEOUT_MS}ms; ` +
+            'the streaming consumer callback may still be firing.',
+        );
+      }
+    };
+  }
+}
+
+
+// Re-cast typed errors on every native entrypoint — instance method,
+// static factory, or free function. The Rust binding tags every
+// `thetadatadx::Error` with a `[ClassName] ...` prefix on the napi
+// `reason`; this interceptor parses it and re-throws the matching
+// subclass so the caller can branch on `instanceof`. Errors without
+// the prefix (napi argument coercion, etc.) surface unchanged. The
+// single helper keeps the sync-throw and async-rejection handling
+// identical across every call shape — there is no second copy of the
+// try/`rethrowTyped` logic to drift.
+function installTypedErrorInterceptor(original, boundThis) {
+  return function typedErrorBoundary(...args) {
+    let result;
+    try {
+      result = original.apply(boundThis !== undefined ? boundThis : this, args);
+    } catch (err) {
+      rethrowTyped(err);
+    }
+    // napi-rs async methods return a Promise; intercept the
+    // rejection without altering the resolved value.
+    if (result && typeof result.then === 'function') {
+      return result.then(
+        (value) => value,
+        (err) => rethrowTyped(err),
+      );
+    }
+    return result;
+  };
+}
+
+// Intrinsic own props every function carries; never wrappable members.
+const FUNCTION_INTRINSICS = new Set(['prototype', 'length', 'name', 'constructor']);
+
+// `true` when `value` is a native class constructor rather than a free
+// function. napi-rs emits both as plain (writable-`prototype`)
+// functions, so the ES2015 `prototype` non-writability test does not
+// apply; a class is distinguished structurally — it carries instance
+// members on its prototype and/or static methods on itself, whereas a
+// free function's prototype holds only `constructor` and it has no own
+// statics.
+function isNativeClass(value) {
+  if (typeof value !== 'function') return false;
+  const proto = value.prototype;
+  if (proto && Object.getOwnPropertyNames(proto).some((n) => n !== 'constructor')) {
+    return true;
+  }
+  return Object.getOwnPropertyNames(value).some(
+    (n) => !FUNCTION_INTRINSICS.has(n) && typeof value[n] === 'function',
+  );
+}
+
+// Re-cast typed errors thrown by a class's instance methods. Instance
+// methods live on `klass.prototype` and napi-rs emits them as writable
+// data properties, so they are patched in place. Static / factory
+// methods cannot be patched this way — napi-rs seals them as
+// non-writable, non-configurable own props of the constructor — so
+// those are re-exposed through a subclass below.
+function wrapInstanceMethods(klass) {
+  if (!klass || !klass.prototype) return;
+  for (const name of Object.getOwnPropertyNames(klass.prototype)) {
+    if (name === 'constructor') continue;
+    const desc = Object.getOwnPropertyDescriptor(klass.prototype, name);
+    if (!desc || typeof desc.value !== 'function') continue;
+    klass.prototype[name] = installTypedErrorInterceptor(desc.value);
+  }
+}
+
+// Re-expose a native class through a thin subclass whose static methods
+// carry the typed-error interceptor. napi-rs seals factory statics
+// (`Client.connectFromFile`, `Contract.option`, ...) as
+// non-writable, non-configurable own props, so they cannot be patched
+// in place; a subclass owns fresh static slots that shadow them while
+// inheriting everything else. Each wrapped static invokes the native
+// static with `this` bound to the native class, so the value it returns
+// is a genuine native instance — `result instanceof NativeClass` stays
+// true. `Symbol.hasInstance` defers to the native class so
+// `x instanceof Exported` continues to recognise those native instances
+// even though their prototype chain points at the native class, not the
+// subclass. Returns the native class unchanged when it has no statics
+// (nothing to re-expose), so non-factory classes keep their identity.
+function wrapClassStatics(klass) {
+  const staticNames = Object.getOwnPropertyNames(klass).filter(
+    (n) => !FUNCTION_INTRINSICS.has(n) && typeof klass[n] === 'function',
+  );
+  if (staticNames.length === 0) return klass;
+
+  const Exported = class extends klass {};
+  for (const name of staticNames) {
+    const nativeStatic = klass[name];
+    Object.defineProperty(Exported, name, {
+      value: installTypedErrorInterceptor(nativeStatic, klass),
+      writable: true,
+      enumerable: false,
+      configurable: true,
+    });
+  }
+  // Native factory statics return native-class instances, never
+  // subclass instances; keep `instanceof Exported` recognising them.
+  Object.defineProperty(Exported, Symbol.hasInstance, {
+    value: (inst) => inst instanceof klass,
+    configurable: true,
+  });
+  // Preserve the readable class name (`extends` would otherwise leave
+  // the anonymous-class name empty).
+  Object.defineProperty(Exported, 'name', {
+    value: klass.name,
+    configurable: true,
+  });
+  return Exported;
+}
+
+// Every exported native class: patch its instance methods in place,
+// then re-expose it (static-wrapped). Discovered structurally so a
+// newly added native class is covered with no edit here. Aliased
+// exports (`Contract` shares `ContractRef`'s constructor) are
+// processed once per distinct native constructor — keyed by identity —
+// so instance methods are not double-wrapped and every alias receives
+// the same re-exposed subclass.
+const exportedClasses = {};
+const wrappedByNativeClass = new Map();
+for (const name of Object.getOwnPropertyNames(native)) {
+  const value = native[name];
+  if (!isNativeClass(value)) continue;
+  let wrapped = wrappedByNativeClass.get(value);
+  if (wrapped === undefined) {
+    wrapInstanceMethods(value);
+    wrapped = wrapClassStatics(value);
+    wrappedByNativeClass.set(value, wrapped);
+  }
+  exportedClasses[name] = wrapped;
+}
+
+// Present `StreamView.batches(...)` as the columnar `AsyncIterable`
+// reader: the native method returns a `RecordBatchStreamHandle` (Arrow IPC
+// transport); wrap it in the JS `RecordBatchStream` so the user gets
+// `for await (const batch of reader)` over apache-arrow `RecordBatch`
+// values plus `close()` / `Symbol.asyncDispose`. Done here, after the
+// generic typed-error wrapping above, so the handle's errors still
+// reclassify. The native method stays `async`, so the patched method
+// awaits and re-wraps. The forwarder lives in `record_batch_forwarder.js`
+// (internal, not exported) so the test suite drives the real call shape
+// against a stub native method rather than a reimplementation.
+if (native.StreamView && native.StreamView.prototype) {
+  const nativeBatches = native.StreamView.prototype.batches;
+  if (typeof nativeBatches === 'function') {
+    native.StreamView.prototype.batches = wrapStreamViewBatches(
+      nativeBatches,
+      RecordBatchStream,
+    );
+  }
+}
+
+// Free functions (e.g. `calendarDayToArrowIpc`, `eodTickToArrowIpc`)
+// are exported directly on the native binding, not on a class. Wrap
+// every own function-valued export that is not a class so a
+// `[ClassName] ...` error raised inside a free function reclassifies
+// the same way it does on a method — one rule: any native export
+// reclassifies typed errors.
+const exportedFreeFns = {};
+for (const name of Object.getOwnPropertyNames(native)) {
+  const value = native[name];
+  if (typeof value !== 'function' || isNativeClass(value)) continue;
+  exportedFreeFns[name] = installTypedErrorInterceptor(value);
+}
+
+// Re-export the entire native surface plus the StreamingSession class.
+// `Object.assign` rather than spread so non-enumerable properties on
+// the napi binding survive. The static-wrapped classes
+// (`exportedClasses`) and reclassifying free functions
+// (`exportedFreeFns`) shadow their raw native counterparts so every
+// public entrypoint reaches the typed-error hierarchy.
+//
+// `Contract` aliases `ContractRef` — napi-rs exposes the fluent
+// contract type under the `ContractRef` symbol because `Contract`
+// already names the FPSS event-payload data class. The public-facing
+// surface documented in the quickstart is `Contract.stock("AAPL")` /
+// `Contract.option(...)`, so the alias makes the JS export agree with
+// the docs without a second pyclass.
+module.exports = Object.assign({}, native, exportedClasses, exportedFreeFns, {
+  StreamingSession,
+  // The JS-side columnar reader returned by `client.stream.batches(...)`.
+  RecordBatchStream,
+  // The documented `Contract` name resolves to the same static-wrapped
+  // export as `ContractRef`, so `Contract.option(...)` reclassifies too.
+  Contract: exportedClasses.ContractRef ?? native.ContractRef,
+  ThetaDataError,
+  AuthenticationError,
+  InvalidCredentialsError,
+  SubscriptionError,
+  RateLimitError,
+  InvalidParameterError,
+  NotFoundError,
+  DeadlineExceededError,
+  UnavailableError,
+  NetworkError,
+  SchemaMismatchError,
+  StreamError,
+  ConfigError,
+});