@xbbg/core 1.3.1 → 1.4.2

package/dist/index.js

@@ -22,7 +22,7 @@ function tableFromNativeArrowBatch(batch) {
     return new apacheArrow.Field(column.name, type, column.nullable);
   });
   const children = batch.columns.map((column) => dataFromColumn(column, retainedBuffers));
-  const schema = new apacheArrow.Schema(fields);
+  const schema = new apacheArrow.Schema(fields, new Map(Object.entries(batch.metadata)));
   const structData = apacheArrow.makeData({
     children,
     length: batch.numRows,
@@ -1078,7 +1078,83 @@ var TA_DEFAULTS = Object.freeze({
 });
 var MKTDATA_SERVICE = "//blp/mktdata";
 function toArrowTableFromNative(batch) {
-  return tableFromNativeArrowBatch(batch);
+  return attachResultMetadata(tableFromNativeArrowBatch(batch), batch.metadata);
+}
+var METADATA_KEY_EID_DATA = "xbbg.eid_data";
+var METADATA_KEY_SECURITY_ERRORS = "xbbg.security_errors";
+var METADATA_KEY_FIELD_EXCEPTIONS = "xbbg.field_exceptions";
+function metadataRecordFromMap(metadata) {
+  return Object.fromEntries(metadata.entries());
+}
+function parseJsonMetadata(metadata, key, guard) {
+  const raw = metadata[key];
+  if (raw === void 0) {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return guard(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function isNumberArrayRecord(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  return Object.values(value).every(
+    (entry) => Array.isArray(entry) && entry.every((eid) => typeof eid === "number")
+  );
+}
+function isMetadataError(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  const { category, code, message, subcategory } = value;
+  return (category === void 0 || typeof category === "string") && (code === void 0 || typeof code === "string" || typeof code === "number") && (message === void 0 || typeof message === "string") && (subcategory === void 0 || typeof subcategory === "string");
+}
+function isMetadataErrorRecord(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  return Object.values(value).every(isMetadataError);
+}
+function isFieldException(value) {
+  if (!isMetadataError(value)) {
+    return false;
+  }
+  if (!("field" in value)) {
+    return true;
+  }
+  return typeof value.field === "string";
+}
+function isFieldExceptionRecord(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  return Object.values(value).every(
+    (entry) => Array.isArray(entry) && entry.every(isFieldException)
+  );
+}
+function attachResultMetadata(result, metadata) {
+  const eidData = parseJsonMetadata(metadata, METADATA_KEY_EID_DATA, isNumberArrayRecord);
+  const securityErrors = parseJsonMetadata(
+    metadata,
+    METADATA_KEY_SECURITY_ERRORS,
+    isMetadataErrorRecord
+  );
+  const fieldExceptions = parseJsonMetadata(
+    metadata,
+    METADATA_KEY_FIELD_EXCEPTIONS,
+    isFieldExceptionRecord
+  );
+  Object.defineProperties(result, {
+    eidData: { enumerable: true, value: eidData },
+    fieldExceptions: { enumerable: true, value: fieldExceptions },
+    metadata: { enumerable: true, value: { ...metadata } },
+    securityErrors: { enumerable: true, value: securityErrors }
+  });
+  return result;
 }
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -1086,6 +1162,12 @@ function isPlainObject(value) {
 function toRequestString(value) {
   return String(value);
 }
+function getLegacySecurityOverrides(params) {
+  if ("securityOverrides" in params) {
+    return params.securityOverrides;
+  }
+  return void 0;
+}
 function mapObjectToPairs(obj) {
   if (obj === void 0) {
     return void 0;
@@ -1095,6 +1177,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 +1490,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;
 }
@@ -1374,13 +1638,15 @@ function normalizeBackend(backend) {
 }
 function ipcToBackend(buffer, backend) {
   const selected = normalizeBackend(backend);
+  const table = apacheArrow.tableFromIPC(buffer);
+  const metadata = metadataRecordFromMap(table.schema.metadata);
   if (selected === Backend.JSON) {
-    return [...apacheArrow.tableFromIPC(buffer)];
+    return attachResultMetadata([...table], metadata);
   }
   if (selected === Backend.POLARS) {
     return loadPolars().readIPC(buffer);
   }
-  return apacheArrow.tableFromIPC(buffer);
+  return attachResultMetadata(table, metadata);
 }
 var configuredEngineConfig;
 var configuredEnginePromise;
@@ -1616,9 +1882,58 @@ var Engine = class _Engine {
       throw wrapError(error);
     }
   }
+  /**
+   * 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.
+   */
+  async seatType() {
+    try {
+      return await this.inner.seatType();
+    } catch (error) {
+      throw wrapError(error);
+    }
+  }
+  /**
+   * 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.
+   */
+  async checkEntitlements(service, eids) {
+    try {
+      return await this.inner.checkEntitlements(service, eids);
+    } catch (error) {
+      throw wrapError(error);
+    }
+  }
+  /**
+   * 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.
+   */
+  async identityIsAuthorized(service) {
+    try {
+      return await this.inner.identityIsAuthorized(service);
+    } catch (error) {
+      throw wrapError(error);
+    }
+  }
   async request(params) {
     const backend = normalizeBackend(params.backend);
-    const { backend: _discarded, ...nativeParams } = params;
+    const { backend: _discarded, overrides, ...rest } = params;
+    const legacySecurityOverrides = getLegacySecurityOverrides(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 +1942,15 @@ var Engine = class _Engine {
     }
   }
   async requestRaw(params) {
+    const { overrides, ...rest } = params;
+    const legacySecurityOverrides = getLegacySecurityOverrides(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);
     }
@@ -1640,9 +1962,10 @@ var Engine = class _Engine {
       fields,
       format: options.format,
       includeSecurityErrors: Boolean(options.includeSecurityErrors),
+      returnEids: options.returnEids,
       kwargs: mapObjectToPairs(options.kwargs),
       operation: "ReferenceDataRequest",
-      overrides: mapObjectToPairs(options.overrides),
+      overrides: options.overrides,
       securities: tickers,
       service: "//blp/refdata",
       validateFields: options.validateFields
@@ -1654,9 +1977,10 @@ var Engine = class _Engine {
       extractor: "bulk",
       fields,
       format: options.format,
+      returnEids: options.returnEids,
       kwargs: mapObjectToPairs(options.kwargs),
       operation: "ReferenceDataRequest",
-      overrides: mapObjectToPairs(options.overrides),
+      overrides: options.overrides,
       securities: tickers,
       service: "//blp/refdata",
       validateFields: options.validateFields
@@ -1669,9 +1993,10 @@ var Engine = class _Engine {
       extractor: "histdata",
       fields,
       format: options.format,
+      returnEids: options.returnEids,
       kwargs: mapObjectToPairs(options.kwargs),
       operation: "HistoricalDataRequest",
-      overrides: mapObjectToPairs(options.overrides),
+      overrides: options.overrides,
       securities: tickers,
       service: "//blp/refdata",
       startDate: formatDate(options.start),
@@ -1732,7 +2057,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 +2064,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 +2131,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 +2612,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 +2762,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 +2783,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;