@xbbg/core 1.3.0 → 1.4.1

package/README.md

@@ -104,6 +104,7 @@ npm run bench:subscription-replay -- --fixture tmp/xbtusd-ticks.jsonl --iteratio
 
 ```typescript
 import * as xbbg from '@xbbg/core';
+import { bdp, ovr } from '@xbbg/core';
 
 xbbg.configure({
   host: 'localhost',
@@ -138,6 +139,19 @@ const zfpEngine = await xbbg.connect({
 const hist = await xbbg.blp.abdh(['AAPL US Equity'], ['PX_LAST'], '2024-01-01', '2024-12-31');
 const ref = await xbbg.blp.abdp(['AAPL US Equity'], ['PX_LAST', 'SECURITY_NAME']);
 const bulk = await xbbg.blp.abds(['ES1 Index'], ['FUT_CHAIN_LAST_TRADE_DATES']);
+
+// Composable override helper
+await bdp(['AAPL US Equity'], ['CRNCY_ADJ_PX_LAST'], {
+  overrides: ovr({ EQY_FUND_CRNCY: 'EUR' }),
+});
+await bdp(['AAPL US Equity', 'MSFT US Equity'], ['CRNCY_ADJ_PX_LAST'], {
+  overrides: ovr({
+    EQY_FUND_CRNCY: 'USD',
+    'AAPL US Equity': ovr({ EQY_FUND_CRNCY: 'EUR' }),
+    'MSFT US Equity': ovr({ EQY_FUND_CRNCY: 'JPY' }),
+  }),
+});
+
 const bars = await xbbg.blp.abdib('AAPL US Equity', '2024-12-01', 5);
 const ticks = await xbbg.blp.abdtick(
   'AAPL US Equity',
@@ -230,6 +244,7 @@ const px = await engine.currencyConversion('700 HK Equity', 'USD', '20240101', '
 - `zfpRemote` (`'8194'` or `'8196'`) for Bloomberg-assigned ZFP endpoints in an entitled environment; do not combine it with `host`/`port`/`servers`/`socks5`
 - `socks5` for proxied access to already-provisioned direct Bloomberg endpoints
 - `retryPolicy`, `numStartAttempts`, and recovery settings for reconnect behavior
+- `shardRequests`, `shardThreshold`, `shardChunkSize`, and `shardMaxConcurrent` for opt-in sharding of wide multi-security `bdp`/`bdh` requests
 
 The JS binding forwards these fields directly to the Rust engine, so Node can configure the same auth and transport features already available in the core runtime. Invalid transport combinations such as `zfpRemote` plus direct hosts fail during configuration instead of silently connecting to `localhost:8194`.
 

package/dist/index.d.ts

@@ -122,6 +122,14 @@ interface EngineConfig {
     zfpRemote?: '8194' | '8196';
     requestPoolSize?: number;
     subscriptionPoolSize?: number;
+    /** Enable request sharding for eligible multi-security bdp/bdh requests. Default false. */
+    shardRequests?: boolean;
+    /** Minimum securities before request sharding applies. Default 20. */
+    shardThreshold?: number;
+    /** Maximum securities per sharded request. Default 16. */
+    shardChunkSize?: number;
+    /** Maximum concurrent shard requests per user request. Default 4. */
+    shardMaxConcurrent?: number;
     validationMode?: string;
     subscriptionFlushThreshold?: number;
     maxEventQueueSize?: number;
@@ -161,7 +169,7 @@ interface RequestInput {
     securities?: readonly string[];
     security?: string;
     fields?: readonly string[];
-    overrides?: readonly StringPair[];
+    overrides?: OverridesInput;
     elements?: readonly StringPair[];
     kwargs?: readonly StringPair[];
     jsonElements?: string;
@@ -197,8 +205,34 @@ interface FieldInfo {
 }
 type PrimitiveValue = string | number | boolean;
 type OverridesMap = Record<string, PrimitiveValue>;
+type OverrideValue = PrimitiveValue | Date | {
+    toJSDate: () => Date;
+};
+interface OverrideObject {
+    readonly [key: string]: OverrideValue | OverrideNestedSource;
+}
+type OverrideNestedSource = OverrideObject | OverrideSpecLike | readonly OverrideEntry[];
+interface SecurityOverrideSpec {
+    readonly security: string;
+    readonly overrides: readonly StringPair[];
+}
+interface OverrideSpecLike {
+    readonly pairs: readonly StringPair[];
+    readonly securityOverrides: readonly SecurityOverrideSpec[];
+    toPairs(): StringPair[];
+    toObject(): OverridesMap;
+    toSecurityOverrides(): SecurityOverrideSpec[];
+    merge(...sources: OverrideSource[]): OverrideSpecLike;
+    forSecurity(security: string, ...sources: OverrideSource[]): OverrideSpecLike;
+}
+type OverrideEntry = {
+    readonly key: string;
+    readonly value: OverrideValue | OverrideNestedSource;
+} | readonly [string, OverrideValue | OverrideNestedSource];
+type OverrideSource = OverrideObject | OverrideSpecLike | readonly OverrideEntry[];
+type OverridesInput = OverrideSource;
 interface BdpOptions {
-    overrides?: OverridesMap;
+    overrides?: OverridesInput;
     kwargs?: OverridesMap;
     format?: string;
     backend?: BackendKind;
@@ -208,7 +242,7 @@ interface BdpOptions {
 interface BdhOptions {
     start?: DateLike;
     end?: DateLike;
-    overrides?: OverridesMap;
+    overrides?: OverridesInput;
     kwargs?: OverridesMap;
     format?: string;
     backend?: BackendKind;
@@ -253,13 +287,13 @@ interface BeqsOptions {
     asof?: DateLike;
     screenType?: string;
     group?: string;
-    overrides?: OverridesMap;
+    overrides?: OverridesInput;
     kwargs?: OverridesMap;
     format?: string;
     backend?: BackendKind;
 }
 interface BsrchOptions {
-    overrides?: OverridesMap;
+    overrides?: OverridesInput;
     kwargs?: OverridesMap;
     format?: string;
     backend?: BackendKind;
@@ -289,7 +323,7 @@ interface BlkpOptions {
     backend?: BackendKind;
 }
 interface RequestOptions {
-    overrides?: OverridesMap;
+    overrides?: OverridesInput;
     kwargs?: OverridesMap;
     format?: string;
     backend?: BackendKind;
@@ -533,6 +567,18 @@ declare function formatDateTime(value: DateTimeLike | undefined | null): string
 declare const CDX_INFO_FIELDS: readonly string[];
 declare const CDX_PRICING_FIELDS: readonly string[];
 declare const CDX_RISK_FIELDS: readonly string[];
+declare class OverrideSpec implements OverrideSpecLike {
+    readonly pairs: readonly StringPair[];
+    readonly securityOverrides: readonly SecurityOverrideSpec[];
+    constructor(pairs: readonly StringPair[], securityOverrides?: readonly SecurityOverrideSpec[]);
+    [Symbol.iterator](): Iterator<StringPair>;
+    toPairs(): StringPair[];
+    toObject(): OverridesMap;
+    toSecurityOverrides(): SecurityOverrideSpec[];
+    merge(...sources: OverrideSource[]): OverrideSpec;
+    forSecurity(security: string, ...sources: OverrideSource[]): OverrideSpec;
+}
+declare function ovr(...sources: OverrideSource[]): OverrideSpec;
 interface RawStudy {
     studyType?: string;
     study?: string;
@@ -665,7 +711,7 @@ declare function abdp(tickers: string | readonly string[], fields: string | read
 declare function bdp(tickers: string | readonly string[], fields: string | readonly string[], options?: BdpOptions): Promise<unknown>;
 declare function abdh(tickers: string | readonly string[], fields: string | readonly string[], start?: DateLike | BdhOptions, end?: DateLike, options?: BdhOptions): Promise<unknown>;
 declare function bdh(tickers: string | readonly string[], fields: string | readonly string[], options?: BdhOptions): Promise<unknown>;
-declare function abds(tickers: string | readonly string[], fields: string | readonly string[], overrides?: OverridesMap, options?: BdpOptions): Promise<unknown>;
+declare function abds(tickers: string | readonly string[], fields: string | readonly string[], overrides?: OverridesInput, options?: BdpOptions): Promise<unknown>;
 declare function bds(tickers: string | readonly string[], fields: string | readonly string[], options?: BdpOptions): Promise<unknown>;
 declare function abdib(ticker: string, dt?: DateTimeLike | BdibOptions, interval?: number | BdibOptions, options?: BdibOptions): Promise<unknown>;
 declare function bdib(ticker: string, options?: BdibOptions): Promise<unknown>;
@@ -746,4 +792,4 @@ declare function version(): string;
 declare const setLogLevel: (level: string) => void;
 declare const getLogLevel: () => string;
 
-export { type ActiveCdxOptions, ArrowSubscription, type AuthConfig, Backend, type BackendKind, type BdhOptions, type BdibOptions, type BdpOptions, type BdtickOptions, type BeqsOptions, type BfldsOptions, type BlkpOptions, BlpError, BlpInternalError, BlpLimitError, BlpRequestError, BlpSessionError, BlpTimeoutError, BlpValidationError, type BqlOptions, type BqrOptions, type BsrchOptions, type BtaOptions, CDX_INFO_FIELDS, CDX_PRICING_FIELDS, CDX_RISK_FIELDS, type CdxOptions, type CdxTickerInfo, type CorporateBondsOptions, type DateLike, type DateTimeLike, type DividendOptions, type DividendYieldOptions, Engine, type EngineConfig, type EtfHoldingsOptions, type ExchangeInfoResult, type ExchangeOverrideInput, FieldHandle, type FieldInfo, Format, type FormatKind, type FuturesCandidate, type FuturesCurveOptions, type FuturesResolveOptions, type FxPairInfo, type IndexMembersOptions, type MarketRule, type OverridesMap, type PreferredsOptions, type PrimitiveValue, type RecipeBackendOptions, type RequestInput, type RequestOptions, type ServerAddress, type SessionWindowsInfo, type Socks5Config, type StreamOptions, type StringPair, Subscription, type SubscriptionStats, Tick, type TickValue, type TickerParts, type TimeRange, type TlsConfig, type TurnoverOptions, type VolFieldSpec, type VolSurfaceOptions, type VolSurfacePreset, type YasOptions, abdh, abdib, abdp, abds, abdtick, asubscribe, bdh, bdib, bdp, bds, bdtick, blp, configure, connect, ext, formatDate, formatDateTime, getLogLevel, setLogLevel, subscribe, version, wrapError };
+export { type ActiveCdxOptions, ArrowSubscription, type AuthConfig, Backend, type BackendKind, type BdhOptions, type BdibOptions, type BdpOptions, type BdtickOptions, type BeqsOptions, type BfldsOptions, type BlkpOptions, BlpError, BlpInternalError, BlpLimitError, BlpRequestError, BlpSessionError, BlpTimeoutError, BlpValidationError, type BqlOptions, type BqrOptions, type BsrchOptions, type BtaOptions, CDX_INFO_FIELDS, CDX_PRICING_FIELDS, CDX_RISK_FIELDS, type CdxOptions, type CdxTickerInfo, type CorporateBondsOptions, type DateLike, type DateTimeLike, type DividendOptions, type DividendYieldOptions, Engine, type EngineConfig, type EtfHoldingsOptions, type ExchangeInfoResult, type ExchangeOverrideInput, FieldHandle, type FieldInfo, Format, type FormatKind, type FuturesCandidate, type FuturesCurveOptions, type FuturesResolveOptions, type FxPairInfo, type IndexMembersOptions, type MarketRule, type OverrideEntry, type OverrideNestedSource, type OverrideObject, type OverrideSource, OverrideSpec, type OverrideSpecLike, type OverrideValue, type OverridesInput, type OverridesMap, type PreferredsOptions, type PrimitiveValue, type RecipeBackendOptions, type RequestInput, type RequestOptions, type SecurityOverrideSpec, type ServerAddress, type SessionWindowsInfo, type Socks5Config, type StreamOptions, type StringPair, Subscription, type SubscriptionStats, Tick, type TickValue, type TickerParts, type TimeRange, type TlsConfig, type TurnoverOptions, type VolFieldSpec, type VolSurfaceOptions, type VolSurfacePreset, type YasOptions, abdh, abdib, abdp, abds, abdtick, asubscribe, bdh, bdib, bdp, bds, bdtick, blp, configure, connect, ext, formatDate, formatDateTime, getLogLevel, ovr, setLogLevel, subscribe, version, wrapError };

package/dist/index.js

@@ -1095,6 +1095,189 @@ function mapObjectToPairs(obj) {
     value: toRequestString(value)
   }));
 }
+var OVR_SOURCE_TYPE_ERROR = "ovr() expects objects, OverrideSpec, or arrays of override entries";
+function normalizeOverrideValue(value) {
+  if (value instanceof Date || hasToJSDate(value)) {
+    return formatDate(value) ?? "";
+  }
+  return String(value);
+}
+function isOverrideSpecLike(value) {
+  return isPlainObject(value) && Array.isArray(value.pairs) && typeof value.toPairs === "function" && typeof value.toObject === "function" && typeof value.merge === "function";
+}
+function isOverrideObject(value) {
+  return isPlainObject(value) && !(value instanceof Date) && !hasToJSDate(value) && !isOverrideSpecLike(value) && !ArrayBuffer.isView(value);
+}
+function normalizeOverrideEntry(entry) {
+  if (Array.isArray(entry)) {
+    if (entry.length !== 2) {
+      throw new TypeError(OVR_SOURCE_TYPE_ERROR);
+    }
+    return [String(entry[0]), entry[1]];
+  }
+  if (isPlainObject(entry) && "key" in entry && "value" in entry) {
+    return [String(entry.key), entry.value];
+  }
+  throw new TypeError(OVR_SOURCE_TYPE_ERROR);
+}
+function createOverrideState() {
+  return {
+    merged: /* @__PURE__ */ new Map(),
+    securityMerged: /* @__PURE__ */ new Map(),
+    securityOrder: []
+  };
+}
+function isPerSecurityOverrideValue(value) {
+  return isOverrideSpecLike(value) || Array.isArray(value) || isOverrideObject(value);
+}
+function addSecurityOverrideSource(security, source, state) {
+  const spec = ovr(source);
+  const pairs = spec.toPairs();
+  if (pairs.length === 0) {
+    return;
+  }
+  let merged = state.securityMerged.get(security);
+  if (merged === void 0) {
+    merged = /* @__PURE__ */ new Map();
+    state.securityMerged.set(security, merged);
+    state.securityOrder.push(security);
+  }
+  for (const pair of pairs) {
+    merged.set(pair.key, pair.value);
+  }
+}
+function addOverridePair(key, value, state) {
+  if (isPerSecurityOverrideValue(value)) {
+    addSecurityOverrideSource(key, value, state);
+    return;
+  }
+  state.merged.set(key, normalizeOverrideValue(value));
+}
+function addOverrideSource(source, state) {
+  if (typeof source === "string" || ArrayBuffer.isView(source)) {
+    throw new TypeError(OVR_SOURCE_TYPE_ERROR);
+  }
+  if (isOverrideSpecLike(source)) {
+    for (const pair of source.toPairs()) {
+      state.merged.set(pair.key, normalizeOverrideValue(pair.value));
+    }
+    const securityOverrides = typeof source.toSecurityOverrides === "function" ? source.toSecurityOverrides() : source.securityOverrides ?? [];
+    for (const entry of securityOverrides) {
+      addSecurityOverrideSource(entry.security, entry.overrides, state);
+    }
+    return;
+  }
+  if (Array.isArray(source)) {
+    for (const entry of source) {
+      const [key, value] = normalizeOverrideEntry(entry);
+      addOverridePair(key, value, state);
+    }
+    return;
+  }
+  if (isOverrideObject(source)) {
+    for (const [key, value] of Object.entries(source)) {
+      addOverridePair(key, value, state);
+    }
+    return;
+  }
+  throw new TypeError(OVR_SOURCE_TYPE_ERROR);
+}
+function securityOverridesFromState(state) {
+  return state.securityOrder.flatMap((security) => {
+    const pairs = state.securityMerged.get(security);
+    if (pairs === void 0 || pairs.size === 0) {
+      return [];
+    }
+    return [
+      {
+        overrides: [...pairs].map(([key, value]) => ({ key, value })),
+        security
+      }
+    ];
+  });
+}
+var OverrideSpec = class {
+  pairs;
+  securityOverrides;
+  constructor(pairs, securityOverrides = []) {
+    this.pairs = Object.freeze(
+      pairs.map(
+        (pair) => Object.freeze({
+          key: pair.key,
+          value: pair.value
+        })
+      )
+    );
+    this.securityOverrides = Object.freeze(
+      securityOverrides.map(
+        (entry) => Object.freeze({
+          overrides: Object.freeze(
+            entry.overrides.map(
+              (pair) => Object.freeze({
+                key: pair.key,
+                value: pair.value
+              })
+            )
+          ),
+          security: entry.security
+        })
+      )
+    );
+  }
+  [Symbol.iterator]() {
+    return this.toPairs()[Symbol.iterator]();
+  }
+  toPairs() {
+    return this.pairs.map((pair) => ({ key: pair.key, value: pair.value }));
+  }
+  toObject() {
+    return Object.fromEntries(this.pairs.map((pair) => [pair.key, pair.value]));
+  }
+  toSecurityOverrides() {
+    return this.securityOverrides.map((entry) => ({
+      overrides: entry.overrides.map((pair) => ({ key: pair.key, value: pair.value })),
+      security: entry.security
+    }));
+  }
+  merge(...sources) {
+    return ovr(this, ...sources);
+  }
+  forSecurity(security, ...sources) {
+    return ovr(this, { [security]: ovr(...sources) });
+  }
+};
+function ovr(...sources) {
+  const state = createOverrideState();
+  for (const source of sources) {
+    addOverrideSource(source, state);
+  }
+  return new OverrideSpec(
+    [...state.merged].map(([key, value]) => ({ key, value })),
+    securityOverridesFromState(state)
+  );
+}
+function mapOverridesToPairs(input) {
+  if (input === void 0) {
+    return void 0;
+  }
+  const spec = ovr(input);
+  if (spec.toSecurityOverrides().length > 0) {
+    throw new TypeError("Per-security overrides are only supported by bdp(), bdh(), and bds()");
+  }
+  return spec.toPairs();
+}
+function mapOverridesToRequestParts(input) {
+  if (input === void 0) {
+    return {};
+  }
+  const spec = ovr(input);
+  const overrides = spec.toPairs();
+  const securityOverrides = spec.toSecurityOverrides();
+  return {
+    ...overrides.length === 0 ? {} : { overrides },
+    ...securityOverrides.length === 0 ? {} : { securityOverrides }
+  };
+}
 var BDTICK_BOOLEAN_KWARGS = Object.freeze([
   ["includeConditionCodes", "includeConditionCodes"],
   ["includeExchangeCodes", "includeExchangeCodes"],
@@ -1225,10 +1408,9 @@ function normalizeRecoveryOptions(options = {}) {
   delete normalized.recoveryRate;
   delete normalized.recovery_rate;
   if (recoveryRate !== void 0) {
-    normalized.overrides = {
-      ...normalized.overrides,
+    normalized.overrides = ovr(normalized.overrides ?? {}, {
       CDS_RR: toRequestString(recoveryRate)
-    };
+    });
   }
   return normalized;
 }
@@ -1618,7 +1800,18 @@ var Engine = class _Engine {
   }
   async request(params) {
     const backend = normalizeBackend(params.backend);
-    const { backend: _discarded, ...nativeParams } = params;
+    const {
+      backend: _discarded,
+      overrides,
+      securityOverrides: legacySecurityOverrides,
+      ...rest
+    } = params;
+    if (legacySecurityOverrides !== void 0) {
+      throw new TypeError(
+        'Use overrides: ovr({ "<SECURITY>": { ... } }) for per-security overrides'
+      );
+    }
+    const nativeParams = { ...rest, ...mapOverridesToRequestParts(overrides) };
     try {
       const buffer = await this.inner.request(nativeParams);
       return ipcToBackend(buffer, backend);
@@ -1627,8 +1820,18 @@ var Engine = class _Engine {
     }
   }
   async requestRaw(params) {
+    const {
+      overrides,
+      securityOverrides: legacySecurityOverrides,
+      ...rest
+    } = params;
+    if (legacySecurityOverrides !== void 0) {
+      throw new TypeError(
+        'Use overrides: ovr({ "<SECURITY>": { ... } }) for per-security overrides'
+      );
+    }
     try {
-      return await this.inner.request(params);
+      return await this.inner.request({ ...rest, ...mapOverridesToRequestParts(overrides) });
     } catch (error) {
       throw wrapError(error);
     }
@@ -1642,7 +1845,7 @@ var Engine = class _Engine {
       includeSecurityErrors: Boolean(options.includeSecurityErrors),
       kwargs: mapObjectToPairs(options.kwargs),
       operation: "ReferenceDataRequest",
-      overrides: mapObjectToPairs(options.overrides),
+      overrides: options.overrides,
       securities: tickers,
       service: "//blp/refdata",
       validateFields: options.validateFields
@@ -1656,7 +1859,7 @@ var Engine = class _Engine {
       format: options.format,
       kwargs: mapObjectToPairs(options.kwargs),
       operation: "ReferenceDataRequest",
-      overrides: mapObjectToPairs(options.overrides),
+      overrides: options.overrides,
       securities: tickers,
       service: "//blp/refdata",
       validateFields: options.validateFields
@@ -1671,7 +1874,7 @@ var Engine = class _Engine {
       format: options.format,
       kwargs: mapObjectToPairs(options.kwargs),
       operation: "HistoricalDataRequest",
-      overrides: mapObjectToPairs(options.overrides),
+      overrides: options.overrides,
       securities: tickers,
       service: "//blp/refdata",
       startDate: formatDate(options.start),
@@ -1732,7 +1935,6 @@ var Engine = class _Engine {
         elements.push({ key: "asOfDate", value: asofFormatted });
       }
     }
-    const overrides = { ...options.overrides };
     return await this.request({
       backend: options.backend,
       elements,
@@ -1740,19 +1942,19 @@ var Engine = class _Engine {
       format: options.format,
       kwargs: mapObjectToPairs(options.kwargs),
       operation: "BeqsRequest",
-      overrides: mapObjectToPairs(overrides),
+      overrides: mapOverridesToPairs(options.overrides),
       service: "//blp/refdata"
     });
   }
   async bsrch(searchSpec, options = {}) {
-    const elements = {
-      Domain: toRequestString(searchSpec),
-      ...options.overrides,
-      ...options.kwargs
-    };
+    const elements = [
+      { key: "Domain", value: toRequestString(searchSpec) },
+      ...mapOverridesToPairs(options.overrides) ?? [],
+      ...mapObjectToPairs(options.kwargs) ?? []
+    ];
     return await this.request({
       backend: options.backend,
-      elements: mapObjectToPairs(elements),
+      elements,
       extractor: "bsrch",
       format: options.format,
       operation: "ExcelGetGridRequest",
@@ -1807,7 +2009,7 @@ var Engine = class _Engine {
       format: options.format,
       kwargs: mapObjectToPairs(options.kwargs),
       operation: "PortfolioDataRequest",
-      overrides: mapObjectToPairs(options.overrides),
+      overrides: mapOverridesToPairs(options.overrides),
       security: toRequestString(portfolio),
       service: "//blp/refdata"
     });
@@ -2288,7 +2490,7 @@ async function bdh(tickers, fields, options = {}) {
 }
 async function abds(tickers, fields, overrides, options = {}) {
   const engine = await getConfiguredEngine();
-  const normalizedOptions = isPlainObject(overrides) ? { ...options, overrides: { ...options.overrides, ...overrides } } : options;
+  const normalizedOptions = overrides === void 0 ? options : { ...options, overrides: ovr(options.overrides ?? {}, overrides) };
   return await engine.bds(toStringArray(tickers), toStringArray(fields), normalizedOptions);
 }
 async function bds(tickers, fields, options = {}) {
@@ -2438,6 +2640,7 @@ exports.CDX_RISK_FIELDS = CDX_RISK_FIELDS;
 exports.Engine = Engine;
 exports.FieldHandle = FieldHandle;
 exports.Format = Format;
+exports.OverrideSpec = OverrideSpec;
 exports.Subscription = Subscription;
 exports.Tick = Tick;
 exports.abdh = abdh;
@@ -2458,6 +2661,7 @@ exports.ext = ext;
 exports.formatDate = formatDate;
 exports.formatDateTime = formatDateTime;
 exports.getLogLevel = getLogLevel;
+exports.ovr = ovr;
 exports.setLogLevel = setLogLevel;
 exports.subscribe = subscribe;
 exports.version = version;