@xbbg/core 1.3.1 → 1.4.2

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

@@ -74,6 +74,26 @@ interface StringPair {
     key: string;
     value: string;
 }
+type SeatType = 'BPS' | 'NONBPS' | 'INVALID';
+interface EntitlementReport {
+    entitled: boolean;
+    failedEids: number[];
+}
+interface BloombergMetadataError {
+    category?: string;
+    code?: string | number;
+    subcategory?: string;
+    message?: string;
+}
+interface BloombergFieldException extends BloombergMetadataError {
+    field?: string;
+}
+interface ResultMetadata {
+    metadata: Record<string, string>;
+    eidData?: Record<string, number[]>;
+    securityErrors?: Record<string, BloombergMetadataError>;
+    fieldExceptions?: Record<string, BloombergFieldException[]>;
+}
 interface ServerAddress {
     host: string;
     port: number;
@@ -122,6 +142,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 +189,7 @@ interface RequestInput {
     securities?: readonly string[];
     security?: string;
     fields?: readonly string[];
-    overrides?: readonly StringPair[];
+    overrides?: OverridesInput;
     elements?: readonly StringPair[];
     kwargs?: readonly StringPair[];
     jsonElements?: string;
@@ -177,6 +205,7 @@ interface RequestInput {
     options?: readonly StringPair[];
     fieldTypes?: readonly StringPair[];
     includeSecurityErrors?: boolean;
+    returnEids?: boolean;
     validateFields?: boolean;
     searchSpec?: string;
     fieldIds?: readonly string[];
@@ -197,21 +226,49 @@ 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;
     includeSecurityErrors?: boolean;
+    returnEids?: boolean;
     validateFields?: boolean;
 }
 interface BdhOptions {
     start?: DateLike;
     end?: DateLike;
-    overrides?: OverridesMap;
+    overrides?: OverridesInput;
     kwargs?: OverridesMap;
     format?: string;
     backend?: BackendKind;
+    returnEids?: boolean;
     validateFields?: boolean;
 }
 interface BdibOptions {
@@ -253,13 +310,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 +346,7 @@ interface BlkpOptions {
     backend?: BackendKind;
 }
 interface RequestOptions {
-    overrides?: OverridesMap;
+    overrides?: OverridesInput;
     kwargs?: OverridesMap;
     format?: string;
     backend?: BackendKind;
@@ -474,6 +531,7 @@ interface NativeArrowZeroCopyBatch {
     readonly kind: 'zeroCopy';
     readonly numRows: number;
     readonly columns: NativeArrowColumn[];
+    readonly metadata: Record<string, string>;
 }
 type NativeUpdateValue = null | boolean | number | string;
 interface NativeSubscriptionUpdate {
@@ -533,6 +591,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;
@@ -595,6 +665,30 @@ declare class Engine {
      * session timeout) — prefer this factory in servers.
      */
     static connect(config?: EngineConfig): Promise<Engine>;
+    /**
+     * Return the Bloomberg identity seat type: "BPS", "NONBPS", or "INVALID".
+     *
+     * Identity operations authorize lazily using the engine auth config when
+     * configured, otherwise the Desktop terminal OS-logon user. The first call
+     * may block for a few seconds and transient failures are retryable.
+     */
+    seatType(): Promise<SeatType>;
+    /**
+     * Check whether the authorized identity is entitled to all supplied EIDs.
+     *
+     * Identity operations authorize lazily using the engine auth config when
+     * configured, otherwise the Desktop terminal OS-logon user. The first call
+     * may block for a few seconds and transient failures are retryable.
+     */
+    checkEntitlements(service: string, eids: readonly number[]): Promise<EntitlementReport>;
+    /**
+     * Return whether the authorized identity may use the Bloomberg service.
+     *
+     * Identity operations authorize lazily using the engine auth config when
+     * configured, otherwise the Desktop terminal OS-logon user. The first call
+     * may block for a few seconds and transient failures are retryable.
+     */
+    identityIsAuthorized(service: string): Promise<boolean>;
     request(params: RequestInput): Promise<unknown>;
     requestRaw(params: RequestInput): Promise<Buffer>;
     bdp(tickers: readonly string[], fields: readonly string[], options?: BdpOptions): Promise<unknown>;
@@ -665,7 +759,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 +840,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, type BloombergFieldException, type BloombergMetadataError, 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 EntitlementReport, 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 ResultMetadata, type SeatType, 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 };