@huskly/ibkr-client 1.1.0 → 1.2.0

package/dist/ibkr/ibkrClient.js

@@ -55,7 +55,6 @@ const QUOTE_FIELDS = [
     "6509", // Market data availability
     "7762", // Unformatted volume
 ].join(",");
-const OPTION_DISCOVERY_MONTH_CONCURRENCY = 1;
 const OPTION_SECDEF_INFO_BATCH_SIZE = 8;
 const OPTION_MARKETDATA_BATCH_SIZE = 100;
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -3279,14 +3278,13 @@ export class IbkrClient {
         };
     }
     /** Discover every listed weekly/monthly expiry in the requested calendar range. */
-    async getOptionExpiries(symbol, right, fromDate, toDate) {
+    async getOptionExpiries(symbol, right, fromDate, toDate, options = {}) {
         const normalized = symbol.trim().toUpperCase();
         const months = monthCodes(fromDate, toDate);
         const contracts = [];
-        for (let index = 0; index < months.length; index += OPTION_DISCOVERY_MONTH_CONCURRENCY) {
-            const batch = months.slice(index, index + OPTION_DISCOVERY_MONTH_CONCURRENCY);
-            const batchContracts = await Promise.all(batch.map((month) => this.discoverOptions(normalized, month, right)));
-            contracts.push(...batchContracts.flatMap((result) => result.contracts));
+        for (const month of months) {
+            const result = await this.discoverOptions(normalized, month, right, options);
+            contracts.push(...result.contracts);
         }
         return [
             ...new Set(contracts
@@ -3295,10 +3293,10 @@ export class IbkrClient {
         ].sort();
     }
     /** Build one exact-expiry chain with canonical OSI symbols and required pricing/greeks. */
-    async getOptionChain(symbol, expiry, right) {
+    async getOptionChain(symbol, expiry, right, options = {}) {
         const month = monthCode(expiry);
         const normalized = symbol.trim().toUpperCase();
-        const discovery = await this.discoverOptions(normalized, month, right);
+        const discovery = await this.discoverOptions(normalized, month, right, options);
         const contracts = discovery.contracts.filter((contract) => contract.expiry === expiry && (right === undefined || contract.right === right));
         if (!contracts.length) {
             throw new Error(`IBKR returned no option contracts for ${symbol} ${expiry}`);
@@ -3306,6 +3304,7 @@ export class IbkrClient {
         const quoted = await this.fetchOptionQuotes(contracts, {
             allowIncomplete: true,
             telemetry: { symbol: normalized, month, right: right ?? null },
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
         });
         if (!quoted.length) {
             throw new Error(`IBKR returned no usable option quotes for ${symbol} ${expiry}`);
@@ -3313,19 +3312,15 @@ export class IbkrClient {
         return quoted;
     }
     /** Return every qualified contract for one exact expiry and side without hiding sparse data. */
-    async getOptionChainSnapshot(symbol, expiry, right) {
+    async getOptionChainSnapshot(symbol, expiry, right, options = {}) {
         const month = monthCode(expiry);
         const normalized = symbol.trim().toUpperCase();
-        const discovery = await this.discoverOptions(normalized, month, right);
+        const discovery = await this.discoverOptions(normalized, month, right, options);
         const contracts = discovery.contracts.filter((contract) => contract.expiry === expiry);
         if (!contracts.length) {
             throw new Error(`IBKR returned no ${right} option contracts for ${symbol} ${expiry}`);
         }
-        return this.fetchOptionChainSnapshot(contracts, discovery.malformedDefinitionCount, {
-            symbol: normalized,
-            month,
-            right,
-        });
+        return this.fetchOptionChainSnapshot(contracts, discovery.malformedDefinitionCount, { symbol: normalized, month, right }, options.signal);
     }
     /** Fetch one exact option quote; null means the contract is not listed. */
     async getOptionQuote(input) {
@@ -3579,30 +3574,41 @@ export class IbkrClient {
         }
         return result;
     }
-    discoverOptions(symbol, month, right) {
+    discoverOptions(symbol, month, right, options = {}) {
         const normalized = symbol.trim().toUpperCase();
+        if (options.signal !== undefined) {
+            return this.loadOptionContracts(normalized, month, right, options.signal);
+        }
         const key = `${normalized}:${month}:${right ?? "*"}`;
-        let pending = this.optionDiscovery.get(key);
-        if (!pending && right !== undefined) {
+        const cached = this.optionDiscovery.get(key);
+        if (cached !== undefined)
+            return cached;
+        let discovery;
+        if (right !== undefined) {
             const complete = this.optionDiscovery.get(`${normalized}:${month}:*`);
             if (complete !== undefined) {
-                pending = complete.then((result) => ({
+                discovery = complete.then((result) => ({
                     contracts: result.contracts.filter((contract) => contract.right === right),
                     malformedDefinitionCount: result.malformedDefinitionCount,
                 }));
             }
         }
-        pending ??= this.loadOptionContracts(normalized, month, right);
+        discovery ??= this.loadOptionContracts(normalized, month, right);
+        const pending = discovery.catch((error) => {
+            if (this.optionDiscovery.get(key) === pending)
+                this.optionDiscovery.delete(key);
+            throw error;
+        });
         this.optionDiscovery.set(key, pending);
         return pending;
     }
-    async loadOptionUnderlying(symbol) {
+    async loadOptionUnderlying(symbol, signal) {
         // This search is load-bearing: IBKR silently returns empty definitions unless the current
         // session has first searched the underlying.
         const search = this.parseSecdefSearchResponse(await this.req({
             path: "iserver/secdef/search",
             params: { symbol },
-        }));
+        }, signal));
         const candidates = search.flatMap((item) => {
             if (!isUnknownRecord(item))
                 return [];
@@ -3641,110 +3647,134 @@ export class IbkrClient {
             throw new Error(`IBKR lost the selected underlying for ${symbol}`);
         return underlying;
     }
-    async loadOptionContracts(symbol, month, right) {
-        const { underlying, requests } = await this.withSecdefPriming(async () => {
-            const searchStarted = this.requestNow();
-            const selectedUnderlying = await this.loadOptionUnderlying(symbol);
-            this.emitOptionDiscoveryTelemetry({
-                phase: "SEARCH",
-                symbol,
-                month,
-                right: right ?? null,
-                durationMs: this.elapsedSince(searchStarted),
-                definitionRequestCount: 0,
-                snapshotBatchCount: 0,
-            });
-            const strikesStarted = this.requestNow();
-            const strikes = await this.req({
-                path: "iserver/secdef/strikes",
-                params: { conid: String(selectedUnderlying.conid), sectype: "OPT", month },
+    async loadOptionContracts(symbol, month, right, callerSignal) {
+        const operation = new AbortController();
+        const abortFromCaller = () => {
+            operation.abort(callerSignal?.reason);
+        };
+        if (callerSignal?.aborted)
+            abortFromCaller();
+        else
+            callerSignal?.addEventListener("abort", abortFromCaller, { once: true });
+        try {
+            const { underlying, requests } = await this.withSecdefPriming(async () => {
+                const searchStarted = this.requestNow();
+                const selectedUnderlying = await this.loadOptionUnderlying(symbol, operation.signal);
+                this.emitOptionDiscoveryTelemetry({
+                    phase: "SEARCH",
+                    symbol,
+                    month,
+                    right: right ?? null,
+                    durationMs: this.elapsedSince(searchStarted),
+                    definitionRequestCount: 0,
+                    snapshotBatchCount: 0,
+                });
+                const strikesStarted = this.requestNow();
+                const strikes = await this.req({
+                    path: "iserver/secdef/strikes",
+                    params: { conid: String(selectedUnderlying.conid), sectype: "OPT", month },
+                }, operation.signal);
+                this.emitOptionDiscoveryTelemetry({
+                    phase: "STRIKES",
+                    symbol,
+                    month,
+                    right: right ?? null,
+                    durationMs: this.elapsedSince(strikesStarted),
+                    definitionRequestCount: 0,
+                    snapshotBatchCount: 0,
+                });
+                const callStrikes = strikes.call ?? [];
+                const putStrikes = strikes.put ?? [];
+                if (callStrikes.length === 0 && putStrikes.length === 0) {
+                    throw new Error(`IBKR returned empty option strikes for ${symbol} ${month} after secdef/search priming`);
+                }
+                const definitionRequests = [
+                    ...(right === undefined || right === "C"
+                        ? callStrikes.map((strike) => ({ strike, right: "C" }))
+                        : []),
+                    ...(right === undefined || right === "P"
+                        ? putStrikes.map((strike) => ({ strike, right: "P" }))
+                        : []),
+                ];
+                return { underlying: selectedUnderlying, requests: definitionRequests };
             });
+            const definitionsStarted = this.requestNow();
+            const contracts = [];
+            let malformedDefinitionCount = 0;
+            for (const batch of chunks(requests, OPTION_SECDEF_INFO_BATCH_SIZE)) {
+                let responses;
+                try {
+                    responses = await Promise.all(batch.map(({ strike, right: requestRight }) => this.req({
+                        path: "iserver/secdef/info",
+                        params: {
+                            conid: String(underlying.conid),
+                            sectype: "OPT",
+                            month,
+                            strike,
+                            right: requestRight,
+                        },
+                    }, operation.signal, (error) => {
+                        operation.abort(error);
+                    })));
+                }
+                catch (error) {
+                    operation.abort(error);
+                    throw error;
+                }
+                for (const response of responses) {
+                    if (!Array.isArray(response)) {
+                        throw new Error(`IBKR returned malformed option definitions for ${symbol} ${month}`);
+                    }
+                    for (const raw of response) {
+                        if (!isUnknownRecord(raw)) {
+                            malformedDefinitionCount += 1;
+                            continue;
+                        }
+                        let contract;
+                        try {
+                            contract = normalizeOptionContract({
+                                conid: typeof raw["conid"] === "number" ? raw["conid"] : undefined,
+                                symbol: typeof raw["symbol"] === "string" ? raw["symbol"] : underlying.symbol,
+                                maturityDate: typeof raw["maturityDate"] === "string" ? raw["maturityDate"] : undefined,
+                                right: typeof raw["right"] === "string" ? raw["right"] : undefined,
+                                strike: typeof raw["strike"] === "string" || typeof raw["strike"] === "number"
+                                    ? raw["strike"]
+                                    : undefined,
+                            });
+                        }
+                        catch {
+                            malformedDefinitionCount += 1;
+                            continue;
+                        }
+                        if (contract)
+                            contracts.push(contract);
+                        else
+                            malformedDefinitionCount += 1;
+                    }
+                }
+            }
             this.emitOptionDiscoveryTelemetry({
-                phase: "STRIKES",
+                phase: "DEFINITIONS",
                 symbol,
                 month,
                 right: right ?? null,
-                durationMs: this.elapsedSince(strikesStarted),
-                definitionRequestCount: 0,
+                durationMs: this.elapsedSince(definitionsStarted),
+                definitionRequestCount: requests.length,
                 snapshotBatchCount: 0,
             });
-            const callStrikes = strikes.call ?? [];
-            const putStrikes = strikes.put ?? [];
-            if (callStrikes.length === 0 && putStrikes.length === 0) {
-                throw new Error(`IBKR returned empty option strikes for ${symbol} ${month} after secdef/search priming`);
-            }
-            const definitionRequests = [
-                ...(right === undefined || right === "C"
-                    ? callStrikes.map((strike) => ({ strike, right: "C" }))
-                    : []),
-                ...(right === undefined || right === "P"
-                    ? putStrikes.map((strike) => ({ strike, right: "P" }))
-                    : []),
-            ];
-            return { underlying: selectedUnderlying, requests: definitionRequests };
-        });
-        const definitionsStarted = this.requestNow();
-        const responses = await Promise.all(requests.map(({ strike, right: requestRight }) => this.req({
-            path: "iserver/secdef/info",
-            params: {
-                conid: String(underlying.conid),
-                sectype: "OPT",
-                month,
-                strike,
-                right: requestRight,
-            },
-        })));
-        this.emitOptionDiscoveryTelemetry({
-            phase: "DEFINITIONS",
-            symbol,
-            month,
-            right: right ?? null,
-            durationMs: this.elapsedSince(definitionsStarted),
-            definitionRequestCount: requests.length,
-            snapshotBatchCount: 0,
-        });
-        if (requests.length === 0)
-            return { contracts: [], malformedDefinitionCount: 0 };
-        const contracts = [];
-        let malformedDefinitionCount = 0;
-        for (const response of responses) {
-            if (!Array.isArray(response)) {
-                throw new Error(`IBKR returned malformed option definitions for ${symbol} ${month}`);
-            }
-            for (const raw of response) {
-                if (!isUnknownRecord(raw)) {
-                    malformedDefinitionCount += 1;
-                    continue;
-                }
-                let contract;
-                try {
-                    contract = normalizeOptionContract({
-                        conid: typeof raw["conid"] === "number" ? raw["conid"] : undefined,
-                        symbol: typeof raw["symbol"] === "string" ? raw["symbol"] : underlying.symbol,
-                        maturityDate: typeof raw["maturityDate"] === "string" ? raw["maturityDate"] : undefined,
-                        right: typeof raw["right"] === "string" ? raw["right"] : undefined,
-                        strike: typeof raw["strike"] === "string" || typeof raw["strike"] === "number"
-                            ? raw["strike"]
-                            : undefined,
-                    });
-                }
-                catch {
-                    malformedDefinitionCount += 1;
-                    continue;
-                }
-                if (contract)
-                    contracts.push(contract);
-                else
-                    malformedDefinitionCount += 1;
+            if (requests.length === 0)
+                return { contracts: [], malformedDefinitionCount: 0 };
+            const unique = [...new Map(contracts.map((contract) => [contract.conid, contract])).values()];
+            if (!unique.length) {
+                throw new Error(`IBKR returned no usable option definitions for ${symbol} ${month} (${String(malformedDefinitionCount)} malformed)`);
             }
+            return { contracts: unique, malformedDefinitionCount };
         }
-        const unique = [...new Map(contracts.map((contract) => [contract.conid, contract])).values()];
-        if (!unique.length) {
-            throw new Error(`IBKR returned no usable option definitions for ${symbol} ${month} (${String(malformedDefinitionCount)} malformed)`);
+        finally {
+            callerSignal?.removeEventListener("abort", abortFromCaller);
         }
-        return { contracts: unique, malformedDefinitionCount };
     }
-    async fetchOptionChainSnapshot(contracts, malformedDefinitionCount, telemetry) {
+    async fetchOptionChainSnapshot(contracts, malformedDefinitionCount, telemetry, signal) {
         const fields = [
             "bid",
             "ask",
@@ -3756,7 +3786,7 @@ export class IbkrClient {
             "timestamp",
         ];
         const missingFieldCounts = Object.fromEntries(fields.map((field) => [field, 0]));
-        const quotes = await this.fetchNullableOptionQuotes(contracts, telemetry);
+        const quotes = await this.fetchNullableOptionQuotes(contracts, telemetry, signal);
         for (const quote of quotes) {
             for (const field of fields) {
                 if (quote[field] === null)
@@ -3771,7 +3801,7 @@ export class IbkrClient {
         };
         return { quotes, diagnostics };
     }
-    async fetchNullableOptionQuotes(contracts, telemetry) {
+    async fetchNullableOptionQuotes(contracts, telemetry, signal) {
         const quotes = [];
         const batches = chunks(contracts, OPTION_MARKETDATA_BATCH_SIZE);
         const snapshotsStarted = this.requestNow();
@@ -3780,12 +3810,9 @@ export class IbkrClient {
                 conids: batch.map((contract) => contract.conid).join(","),
                 fields: OPTION_QUOTE_FIELDS,
             };
-            await this.req({ path: "iserver/marketdata/snapshot", params });
+            await this.req({ path: "iserver/marketdata/snapshot", params }, signal);
             await this.wait(2000);
-            const response = await this.req({
-                path: "iserver/marketdata/snapshot",
-                params,
-            });
+            const response = await this.req({ path: "iserver/marketdata/snapshot", params }, signal);
             if (!Array.isArray(response)) {
                 throw new Error("IBKR returned malformed option market-data snapshots");
             }
@@ -3826,10 +3853,10 @@ export class IbkrClient {
         return quotes;
     }
     async fetchOptionQuotes(contracts, options = {}) {
-        const { allowIncomplete = false, telemetry } = options;
+        const { allowIncomplete = false, telemetry, signal } = options;
         const result = [];
         const skipped = [];
-        for (const quote of await this.fetchNullableOptionQuotes(contracts, telemetry)) {
+        for (const quote of await this.fetchNullableOptionQuotes(contracts, telemetry, signal)) {
             if (quote.bid === null || quote.ask === null || quote.delta === null) {
                 if (allowIncomplete) {
                     skipped.push(quote.symbol);
@@ -4516,8 +4543,8 @@ export class IbkrClient {
             throw this.normalizeHttpError(error);
         }
     }
-    req(input) {
-        return this.scheduledRequest(input, "SAFE_READ");
+    req(input, signal, onTerminalFailure) {
+        return this.scheduledRequest(input, "SAFE_READ", signal, onTerminalFailure);
     }
     historyRequest(input) {
         return this.scheduledRequest(input, "PRICE_HISTORY");
@@ -4525,13 +4552,15 @@ export class IbkrClient {
     singleAttemptRequest(input) {
         return this.scheduledRequest(input, "SINGLE_ATTEMPT");
     }
-    scheduledRequest(input, retryPolicy) {
+    scheduledRequest(input, retryPolicy, signal, onTerminalFailure) {
         return this.requestScheduler.schedule({
             endpoint: this.requestEndpoint(input.path),
             priority: this.requestPriority(input.path),
             secdefInfo: input.path === "iserver/secdef/info",
             retryable: retryPolicy !== "SINGLE_ATTEMPT",
             retryServerErrors: retryPolicy === "PRICE_HISTORY",
+            ...(signal === undefined ? {} : { signal }),
+            ...(onTerminalFailure === undefined ? {} : { onTerminalFailure }),
         }, async () => {
             try {
                 return await this.sendRequest(input);