@xbbg/core 1.2.6 → 1.3.0

package/README.md

@@ -28,6 +28,8 @@ If no packaged addon is available for your platform, build from source locally i
 
 Using the API requires Bloomberg Terminal, B-PIPE, or ZFP access and Bloomberg SDK runtime libraries available on the target system. Configure Bloomberg connectivity and credentials according to your Bloomberg deployment before making requests.
 
+On Windows, `@xbbg/core` prepends the first detected Bloomberg runtime DLL directory before loading the native addon. Explicit `BLPAPI_LIB_DIR` / `BLPAPI_ROOT` values win; otherwise it probes local SDK roots plus standard Terminal DAPI installs including `C:\blp\DAPI` and `C:\Program Files (x86)\Bloomberg\Blp\DAPI`.
+
 `@xbbg/core` is not affiliated with, endorsed by, sponsored by, or approved by Bloomberg Finance L.P. or its affiliates. It does not provide Bloomberg access, credentials, entitlements, data rights, or SDK licenses; users must supply and use those under their own Bloomberg agreements and policies.
 
 ## Release integrity

package/dist/index.d.ts

@@ -34,6 +34,8 @@ declare class BlpRequestError extends BlpError {
     readonly code?: string | number;
     constructor(message: string, options?: BlpRequestErrorOptions);
 }
+declare class BlpLimitError extends BlpRequestError {
+}
 declare class BlpValidationError extends BlpError {
     readonly element?: string;
     readonly suggestion?: string;
@@ -583,7 +585,16 @@ declare class Subscription implements AsyncIterator<Tick>, AsyncIterable<Tick> {
 declare class Engine {
     private inner;
     constructor(host?: string, port?: number);
+    /** Allocate an Engine around an already-constructed native engine. */
+    private static fromInner;
     static withConfig(config?: EngineConfig): Engine;
+    /**
+     * Connect asynchronously: the Bloomberg session connect and service warmup
+     * run off the JS thread. The sync constructor and `withConfig` block the
+     * Node event loop for the duration of the connect (seconds, up to the 30s
+     * session timeout) — prefer this factory in servers.
+     */
+    static connect(config?: EngineConfig): Promise<Engine>;
     request(params: RequestInput): Promise<unknown>;
     requestRaw(params: RequestInput): Promise<Buffer>;
     bdp(tickers: readonly string[], fields: readonly string[], options?: BdpOptions): Promise<unknown>;
@@ -735,4 +746,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, 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 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 };

package/dist/index.js

@@ -463,6 +463,8 @@ var BlpRequestError = class extends BlpError {
     this.code = options.code;
   }
 };
+var BlpLimitError = class extends BlpRequestError {
+};
 var BlpValidationError = class extends BlpError {
   element;
   suggestion;
@@ -476,11 +478,37 @@ var BlpTimeoutError = class extends BlpError {
 };
 var BlpInternalError = class extends BlpError {
 };
+var CODE_PREFIX = /^\[XBBG:([A-Z]+)\]\s*/u;
+function fromCode(code, msg) {
+  switch (code) {
+    case "SESSION":
+      return new BlpSessionError(msg);
+    case "REQUEST":
+      return new BlpRequestError(msg, parseRequestOptions(msg));
+    case "LIMIT":
+      return new BlpLimitError(msg, parseRequestOptions(msg));
+    case "VALIDATION":
+      return new BlpValidationError(msg, parseValidationOptions(msg));
+    case "TIMEOUT":
+      return new BlpTimeoutError(msg);
+    case "CANCELLED":
+    case "INTERNAL":
+      return new BlpInternalError(msg);
+    default:
+      return new BlpError(msg);
+  }
+}
 function wrapError(napiError) {
   if (napiError instanceof BlpError) {
     return napiError;
   }
   const msg = napiError instanceof Error ? napiError.message : typeof napiError === "string" ? napiError : "";
+  const codeMatch = CODE_PREFIX.exec(msg);
+  const nativeCode = codeMatch?.[1];
+  const matchedPrefix = codeMatch?.[0];
+  if (nativeCode !== void 0 && matchedPrefix !== void 0) {
+    return fromCode(nativeCode, msg.slice(matchedPrefix.length));
+  }
   if (msg.includes("Session start failed") || msg.includes("session start failed") || msg.includes("Failed to start session") || msg.includes("Failed to open service") || msg.includes("failed to spawn worker") || msg.includes("connect event failed")) {
     return new BlpSessionError(msg);
   }
@@ -665,53 +693,71 @@ function resolveNativeAddon(repoRoot) {
   }
   return resolveNativeAddonCore({ exists, nativePackage, repoRoot, requirePackage });
 }
-
-// src/index.ts
-var nodeRequire2 = module$1.createRequire(__filename);
-function parsePackageJsonShape(value) {
-  if (isPlainObject(value) && typeof value.version === "string") {
-    return { version: value.version };
-  }
-  throw new TypeError("@xbbg/core package.json is missing a string version field");
+var BLPAPI_RUNTIME_NAMES = Object.freeze([
+  "blpapi3_64.dll",
+  "blpapi3_32.dll",
+  "libblpapi3.dylib",
+  "libblpapi3_64.so",
+  "libblpapi3.so"
+]);
+var WINDOWS_PATH_SEPARATOR = ";";
+var readDirectory = (target) => fs2__default.default.readdirSync(target, { withFileTypes: true });
+function windowsPathKey(value) {
+  return path2__default.default.win32.normalize(value).toLowerCase();
 }
-function isNativeAddon(value) {
-  return isPlainObject(value) && typeof value.JsEngine === "function" && typeof value.getLogLevel === "function" && typeof value.setLogLevel === "function";
+function candidateKey(value, platform) {
+  return platform === "win32" ? windowsPathKey(value) : path2__default.default.resolve(value);
 }
-function requireNativeAddon(modulePath) {
-  const loaded = nodeRequire2(modulePath);
-  if (isNativeAddon(loaded)) {
-    return loaded;
+function pushUnique(candidates, seen, candidate, platform) {
+  if (candidate === void 0 || candidate.length === 0) {
+    return;
   }
-  throw new TypeError(`Native addon ${modulePath} does not expose the expected @xbbg/core surface`);
-}
-function isPolarsModule(value) {
-  return isPlainObject(value) && typeof value.readIPC === "function";
-}
-function requirePolarsModule() {
-  const loaded = nodeRequire2("nodejs-polars");
-  if (isPolarsModule(loaded)) {
-    return loaded;
+  const key = candidateKey(candidate, platform);
+  if (seen.has(key)) {
+    return;
   }
-  throw new TypeError("nodejs-polars did not expose readIPC(buffer)");
+  seen.add(key);
+  candidates.push(candidate);
 }
-function isBdhOptionsInput(value) {
-  return isPlainObject(value) && !(value instanceof Date) && !hasToJSDate(value);
+function windowsDrive(value) {
+  if (value !== void 0 && /^[A-Za-z]:/u.test(value)) {
+    return value.slice(0, 2);
+  }
+  return "C:";
 }
-function isBdibOptionsInput(value) {
-  return isPlainObject(value) && !(value instanceof Date) && !hasToJSDate(value);
+function collectWindowsDapiRootCandidates(env = process.env) {
+  const candidates = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (candidate) => {
+    pushUnique(candidates, seen, candidate, "win32");
+  };
+  const systemDrive = windowsDrive(env.SystemDrive);
+  const systemDriveRoot = `${systemDrive}\\`;
+  add(path2__default.default.win32.join(systemDriveRoot, "blp", "DAPI"));
+  if (systemDrive.toLowerCase() !== "c:") {
+    add(path2__default.default.win32.join("C:\\", "blp", "DAPI"));
+  }
+  const programFilesRoots = [
+    env.ProgramFiles,
+    path2__default.default.win32.join(systemDriveRoot, "Program Files"),
+    env["ProgramFiles(x86)"],
+    path2__default.default.win32.join(systemDriveRoot, "Program Files (x86)")
+  ];
+  for (const root of programFilesRoots) {
+    add(root === void 0 ? void 0 : path2__default.default.win32.join(root, "Bloomberg", "Blp", "DAPI"));
+  }
+  const localAppData = env.LOCALAPPDATA ?? (env.USERPROFILE === void 0 ? void 0 : path2__default.default.win32.join(env.USERPROFILE, "AppData", "Local"));
+  if (localAppData !== void 0) {
+    add(path2__default.default.win32.join(localAppData, "Bloomberg", "DAPI"));
+    add(path2__default.default.win32.join(localAppData, "Bloomberg", "Blp", "DAPI"));
+  }
+  return candidates;
 }
-var packageJson = parsePackageJsonShape(nodeRequire2("../package.json"));
-function containsBlpapiRuntime(dir) {
-  if (dir.length === 0 || !fs2__default.default.existsSync(dir)) {
+function containsBlpapiRuntime(dir, exists2 = fs2__default.default.existsSync) {
+  if (dir.length === 0) {
     return false;
   }
-  return [
-    "blpapi3_64.dll",
-    "blpapi3_32.dll",
-    "libblpapi3.dylib",
-    "libblpapi3_64.so",
-    "libblpapi3.so"
-  ].some((name) => fs2__default.default.existsSync(path2__default.default.join(dir, name)));
+  return BLPAPI_RUNTIME_NAMES.some((name) => exists2(path2__default.default.join(dir, name)));
 }
 function parseVersionParts(name) {
   const parts = name.split(".").map((part) => Number(part));
@@ -740,62 +786,141 @@ function compareSdkRoots(left, right) {
 }
 function pushSdkRuntimeCandidates(candidates, sdkRoot) {
   const resolved = path2__default.default.resolve(sdkRoot);
-  candidates.push(resolved, path2__default.default.join(resolved, "bin"), path2__default.default.join(resolved, "lib"));
+  candidates.push(
+    resolved,
+    path2__default.default.join(resolved, "bin"),
+    path2__default.default.join(resolved, "lib"),
+    path2__default.default.join(resolved, "Lib"),
+    path2__default.default.join(resolved, "lib", "win64"),
+    path2__default.default.join(resolved, "lib", "win32")
+  );
 }
-function resolveVendorSdkRoot(repoRoot) {
+function addSdkRuntimeRoot(add, sdkRoot) {
+  const sdkCandidates = [];
+  pushSdkRuntimeCandidates(sdkCandidates, sdkRoot);
+  for (const candidate of sdkCandidates) {
+    add(candidate);
+  }
+}
+function resolveVendorSdkRoot(repoRoot, exists2 = fs2__default.default.existsSync, readDir = readDirectory) {
   const vendorDir = path2__default.default.join(repoRoot, "vendor", "blpapi-sdk");
-  if (!fs2__default.default.existsSync(vendorDir)) {
+  if (!exists2(vendorDir)) {
     return null;
   }
   const candidates = [vendorDir];
-  for (const entry of fs2__default.default.readdirSync(vendorDir, { withFileTypes: true })) {
+  for (const entry of readDir(vendorDir)) {
     if (entry.isDirectory()) {
       candidates.push(path2__default.default.join(vendorDir, entry.name));
     }
   }
   candidates.sort(compareSdkRoots);
   return candidates.find((candidate) => {
-    const dirs = [candidate, path2__default.default.join(candidate, "bin"), path2__default.default.join(candidate, "lib")];
-    return dirs.some(containsBlpapiRuntime);
+    const dirs = [
+      candidate,
+      path2__default.default.join(candidate, "bin"),
+      path2__default.default.join(candidate, "lib"),
+      path2__default.default.join(candidate, "Lib")
+    ];
+    return dirs.some((dir) => containsBlpapiRuntime(dir, exists2));
   }) ?? null;
 }
-function configureRuntimeSearchPath() {
-  if (process.platform !== "win32") {
-    return;
-  }
+function collectRuntimeSearchCandidates(options = {}) {
+  const env = options.env ?? process.env;
+  const exists2 = options.exists ?? fs2__default.default.existsSync;
+  const platform = options.platform ?? process.platform;
+  const readDir = options.readDir ?? readDirectory;
+  const repoRoot = options.repoRoot ?? path2__default.default.resolve(__dirname, "..", "..");
   const candidates = [];
-  const libDir = process.env.BLPAPI_LIB_DIR;
+  const seen = /* @__PURE__ */ new Set();
+  const add = (candidate) => {
+    pushUnique(candidates, seen, candidate, platform);
+  };
+  const libDir = env.BLPAPI_LIB_DIR;
   if (libDir !== void 0 && libDir.length > 0) {
-    candidates.push(path2__default.default.resolve(libDir));
+    add(path2__default.default.resolve(libDir));
   }
-  const root = process.env.BLPAPI_ROOT;
+  const root = env.BLPAPI_ROOT;
   if (root !== void 0 && root.length > 0) {
-    pushSdkRuntimeCandidates(candidates, root);
+    addSdkRuntimeRoot(add, root);
   }
-  const repoRoot = path2__default.default.resolve(__dirname, "..", "..");
-  const devRoot = process.env.XBBG_DEV_SDK_ROOT;
+  const devRoot = env.XBBG_DEV_SDK_ROOT;
   if (devRoot !== void 0 && devRoot.length > 0) {
-    pushSdkRuntimeCandidates(
-      candidates,
-      path2__default.default.isAbsolute(devRoot) ? devRoot : path2__default.default.resolve(repoRoot, devRoot)
-    );
+    const resolved = path2__default.default.isAbsolute(devRoot) ? devRoot : path2__default.default.resolve(repoRoot, devRoot);
+    addSdkRuntimeRoot(add, resolved);
   }
-  const vendorRoot = resolveVendorSdkRoot(repoRoot);
+  const vendorRoot = resolveVendorSdkRoot(repoRoot, exists2, readDir);
   if (vendorRoot !== null) {
-    pushSdkRuntimeCandidates(candidates, vendorRoot);
+    addSdkRuntimeRoot(add, vendorRoot);
   }
-  for (const candidate of candidates) {
-    if (!containsBlpapiRuntime(candidate)) {
-      continue;
+  if (platform === "win32") {
+    for (const dapiRoot of collectWindowsDapiRootCandidates(env)) {
+      add(dapiRoot);
     }
-    const currentPath = process.env.PATH ?? "";
-    const parts = currentPath.split(";").filter((part) => part.length > 0);
-    if (!parts.includes(candidate)) {
-      process.env.PATH = currentPath.length > 0 ? `${candidate};${currentPath}` : candidate;
+  }
+  return candidates;
+}
+function prependWindowsPath(env, candidate) {
+  const key = Object.keys(env).find((envKey) => envKey.toUpperCase() === "PATH") ?? "PATH";
+  const currentPath = env[key] ?? "";
+  const currentParts = currentPath.split(WINDOWS_PATH_SEPARATOR).filter((part) => part.length > 0);
+  const candidatePathKey = windowsPathKey(candidate);
+  if (currentParts.some((part) => windowsPathKey(part) === candidatePathKey)) {
+    return;
+  }
+  env[key] = currentPath.length > 0 ? `${candidate}${WINDOWS_PATH_SEPARATOR}${currentPath}` : candidate;
+}
+function configureRuntimeSearchPath(options = {}) {
+  const env = options.env ?? process.env;
+  const exists2 = options.exists ?? fs2__default.default.existsSync;
+  const platform = options.platform ?? process.platform;
+  if (platform !== "win32") {
+    return null;
+  }
+  for (const candidate of collectRuntimeSearchCandidates(options)) {
+    if (!containsBlpapiRuntime(candidate, exists2)) {
+      continue;
     }
-    break;
+    prependWindowsPath(env, candidate);
+    return candidate;
+  }
+  return null;
+}
+
+// src/index.ts
+var nodeRequire2 = module$1.createRequire(__filename);
+function parsePackageJsonShape(value) {
+  if (isPlainObject(value) && typeof value.version === "string") {
+    return { version: value.version };
+  }
+  throw new TypeError("@xbbg/core package.json is missing a string version field");
+}
+function isNativeAddon(value) {
+  return isPlainObject(value) && typeof value.JsEngine === "function" && typeof value.getLogLevel === "function" && typeof value.setLogLevel === "function";
+}
+function requireNativeAddon(modulePath) {
+  const loaded = nodeRequire2(modulePath);
+  if (isNativeAddon(loaded)) {
+    return loaded;
   }
+  throw new TypeError(`Native addon ${modulePath} does not expose the expected @xbbg/core surface`);
+}
+function isPolarsModule(value) {
+  return isPlainObject(value) && typeof value.readIPC === "function";
+}
+function requirePolarsModule() {
+  const loaded = nodeRequire2("nodejs-polars");
+  if (isPolarsModule(loaded)) {
+    return loaded;
+  }
+  throw new TypeError("nodejs-polars did not expose readIPC(buffer)");
+}
+function isBdhOptionsInput(value) {
+  return isPlainObject(value) && !(value instanceof Date) && !hasToJSDate(value);
+}
+function isBdibOptionsInput(value) {
+  return isPlainObject(value) && !(value instanceof Date) && !hasToJSDate(value);
 }
+var packageJson = parsePackageJsonShape(nodeRequire2("../package.json"));
 configureRuntimeSearchPath();
 function loadNative() {
   const root = path2__default.default.resolve(__dirname, "..", "..");
@@ -1461,18 +1586,35 @@ var Engine = class _Engine {
       throw wrapError(error);
     }
   }
-  static withConfig(config = {}) {
+  /** Allocate an Engine around an already-constructed native engine. */
+  static fromInner(inner) {
     const maybeEngine = Object.create(_Engine.prototype);
     if (!(maybeEngine instanceof _Engine)) {
       throw new TypeError("Failed to allocate Engine instance");
     }
-    const engine = maybeEngine;
+    maybeEngine.inner = inner;
+    return maybeEngine;
+  }
+  static withConfig(config = {}) {
+    try {
+      return _Engine.fromInner(native.JsEngine.withConfig(config));
+    } catch (error) {
+      throw wrapError(error);
+    }
+  }
+  /**
+   * Connect asynchronously: the Bloomberg session connect and service warmup
+   * run off the JS thread. The sync constructor and `withConfig` block the
+   * Node event loop for the duration of the connect (seconds, up to the 30s
+   * session timeout) — prefer this factory in servers.
+   */
+  static async connect(config) {
     try {
-      engine.inner = native.JsEngine.withConfig(config);
+      const inner = config === void 0 ? await native.JsEngine.connect() : await native.JsEngine.connectWithConfig(config);
+      return _Engine.fromInner(inner);
     } catch (error) {
       throw wrapError(error);
     }
-    return engine;
   }
   async request(params) {
     const backend = normalizeBackend(params.backend);
@@ -2113,7 +2255,7 @@ var Engine = class _Engine {
   }
 };
 async function connect(config) {
-  return await Promise.resolve(config === void 0 ? new Engine() : Engine.withConfig(config));
+  return await Engine.connect(config);
 }
 function configure(configOrHost, port) {
   configuredEngineConfig = normalizeConfigureArgs(configOrHost, port);
@@ -2285,6 +2427,7 @@ exports.ArrowSubscription = ArrowSubscription;
 exports.Backend = Backend;
 exports.BlpError = BlpError;
 exports.BlpInternalError = BlpInternalError;
+exports.BlpLimitError = BlpLimitError;
 exports.BlpRequestError = BlpRequestError;
 exports.BlpSessionError = BlpSessionError;
 exports.BlpTimeoutError = BlpTimeoutError;