gloomberb 0.18.0 → 0.18.2

package/src/utils/format.ts

@@ -1,4 +1,4 @@
-import { fixedUsdRate } from "./currency-units";
+import { fixedUsdRate, minorUnitSign } from "./currency-units";
 
 const currencyFormatters = new Map<string, Intl.NumberFormat>();
 const numberFormatters = new Map<number, Intl.NumberFormat>();
@@ -47,6 +47,15 @@ function getNumberFormatter(decimals: number): Intl.NumberFormat {
  * as a price in it does: USDT101.70.
  */
 function formatMoney(value: number, currency: string, maximumFractionDigits: number): string {
+  // A minor unit is written after the amount: 314.95¢ in US cents, 412.50p in pence.
+  const minor = minorUnitSign(currency);
+  if (minor) {
+    const body = new Intl.NumberFormat("en-US", {
+      minimumFractionDigits: Math.min(2, maximumFractionDigits),
+      maximumFractionDigits,
+    }).format(Math.abs(value));
+    return `${value < 0 && /[1-9]/.test(body) ? "-" : ""}${body}${minor}`;
+  }
   try {
     return getCurrencyFormatter(currency, maximumFractionDigits).format(value);
   } catch {
@@ -67,6 +76,27 @@ export function formatCurrency(
   return formatMoney(value, currency, maximumFractionDigits);
 }
 
+/**
+ * An amount with its currency's code after it (259.36 USD, -5.57 CAD), for a
+ * report read by someone whose own currency shares the sign: $ alone is the
+ * US, Canadian and Australian dollar. The same decimals as `formatCurrency`;
+ * a minor unit keeps its sign (314.95¢, 412.50p).
+ */
+export function formatCurrencyCode(
+  value: number | undefined,
+  currency = "USD",
+  maximumFractionDigits: number = currencyPriceDigits(currency),
+): string {
+  if (value == null || !Number.isFinite(value)) return "—";
+  if (minorUnitSign(currency)) return formatMoney(value, currency, maximumFractionDigits);
+  const code = currency.trim().toUpperCase();
+  const body = new Intl.NumberFormat("en-US", {
+    minimumFractionDigits: Math.min(currencyPriceDigits(code), maximumFractionDigits),
+    maximumFractionDigits,
+  }).format(Math.abs(value));
+  return `${value < 0 && /[1-9]/.test(body) ? "-" : ""}${body} ${code}`;
+}
+
 /** Preserve fractional per-share distributions, including split-adjusted history. */
 export function formatDistributionAmount(value: number | undefined, currency = "USD"): string {
   if (value == null || !Number.isFinite(value)) return "—";

package/src/utils/instrument-identity.ts

@@ -1,4 +1,6 @@
-import type { BrokerContractRef } from "../types/instrument";
+import type { BrokerContractRef, TickerListingRef } from "../types/instrument";
+import { canonicalExchange } from "./exchanges";
+import { optionContractIdentity } from "./options";
 
 const normalized = (value: string | undefined): string => value?.trim().toUpperCase() ?? "";
 
@@ -33,3 +35,38 @@ export function instrumentIdentityKey(instrument: {
     instrument.instrument ? brokerContractIdentityKey(instrument.instrument) : "",
   ].join("|");
 }
+
+/**
+ * Whether two refs name the same contract however a broker routed or filed it: by conId when both
+ * have one; an option by its OCC contract; a share by symbol, currency and terms, where SMART names
+ * a route and not a listing and an ETF may be filed as a stock, though two named listings must agree;
+ * anything else by its definition. Which broker and profile hold it is the caller's to compare.
+ */
+export function sameBrokerContract(held: BrokerContractRef, contract: BrokerContractRef): boolean {
+  if (held.conId !== undefined && contract.conId !== undefined) return held.conId === contract.conId;
+  const option = optionContractIdentity(held);
+  if (option || optionContractIdentity(contract)) return option === optionContractIdentity(contract)
+    && (held.multiplier === undefined || contract.multiplier === undefined || Number(held.multiplier) === Number(contract.multiplier));
+  const stock = (value: BrokerContractRef) => !value.secType || ["STK", "ETF"].includes(value.secType.toUpperCase());
+  if (stock(held) && stock(contract)) {
+    const venue = (value: BrokerContractRef) => [value.exchange, value.primaryExchange].map(canonicalExchange).find((name) => name && name !== "SMART") ?? "";
+    const share = (value: BrokerContractRef) => JSON.stringify([value.symbol.toUpperCase(), (value.localSymbol ?? value.symbol).toUpperCase(), value.currency,
+      value.lastTradeDateOrContractMonth, value.right, value.strike, value.multiplier]);
+    return share(held) === share(contract) && (!venue(held) || !venue(contract) || venue(held) === venue(contract));
+  }
+  const key = (value: BrokerContractRef) => JSON.stringify([
+    value.symbol.toUpperCase(), canonicalExchange(value.exchange), value.secType, value.currency, value.lastTradeDateOrContractMonth,
+    value.right, value.strike, value.multiplier, (value.localSymbol ?? value.symbol).toUpperCase(),
+  ]);
+  return key(held) === key(contract);
+}
+
+/**
+ * Whether a share a broker holds is one of this listing's, for a pane bound to a listing and no
+ * broker contract: in the listing's currency, held through a route (SMART) or on its venue.
+ */
+export function heldOnListing(held: BrokerContractRef, listing: TickerListingRef): boolean {
+  const share = !optionContractIdentity(held) && (!held.secType || ["STK", "ETF"].includes(held.secType.toUpperCase()));
+  if (!share || !listing.currency) return false;
+  return sameBrokerContract(held, { ...held, conId: undefined, exchange: listing.exchange, primaryExchange: undefined, currency: listing.currency });
+}

package/src/utils/options.ts

@@ -27,6 +27,51 @@ export function parseOptionSymbol(symbol: string): { underlying: string; expTs:
   return { underlying: underlying!, expTs, strike, side: side as "C" | "P" };
 }
 
+/** An option ticker's contract as a broker writes it ("UBER 260821C00090000") or as OCC does ("AAPL261218C00300000"). */
+export function parseOptionTicker(symbol: string): ReturnType<typeof parseOptionSymbol> {
+  const contract = parseOptionContract(symbol);
+  if (!contract) return null;
+  return { underlying: contract.underlying, expTs: Math.floor(Date.UTC(contract.year, contract.month - 1, contract.day) / 1000),
+    strike: contract.strike, side: contract.side };
+}
+
+/**
+ * One contract of a chain, on the broker that served it: the underlying's
+ * broker and profile, with the expiry, side, strike and 100-share deliverable
+ * the symbol carries. Null when the underlying is not a broker's or the
+ * symbol is not a contract, and the contract then opens by its symbol alone.
+ */
+export function chainOptionContract(contractSymbol: string, underlying: BrokerContractRef | null | undefined, currency: string): BrokerContractRef | null {
+  const contract = parseOptionContract(contractSymbol);
+  if (!contract || !underlying?.brokerId) return null;
+  const pad = (value: number) => String(value).padStart(2, "0");
+  return {
+    brokerId: underlying.brokerId,
+    ...(underlying.brokerInstanceId ? { brokerInstanceId: underlying.brokerInstanceId } : {}),
+    symbol: contract.underlying,
+    localSymbol: contractSymbol.trim().toUpperCase(),
+    secType: "OPT",
+    currency: currency || underlying.currency || "USD",
+    lastTradeDateOrContractMonth: `${contract.year}${pad(contract.month)}${pad(contract.day)}`,
+    right: contract.side,
+    strike: contract.strike,
+    multiplier: "100",
+  };
+}
+
+/**
+ * The OCC identity of an option contract, from its symbol or its fields,
+ * however a broker writes the date or routes it; null for anything else.
+ */
+export function optionContractIdentity(contract: BrokerContractRef): string | null {
+  if (contract.secType?.toUpperCase() !== "OPT" && contract.secType?.toUpperCase() !== "OPTION") return null;
+  const parsed = parseOptionContract(contract.localSymbol ?? "") ?? parseOptionContract(contract.symbol);
+  if (parsed) return `${parsed.underlying}|${parsed.year}${String(parsed.month).padStart(2, "0")}${String(parsed.day).padStart(2, "0")}|${parsed.side}|${parsed.strike}`;
+  const date = contract.lastTradeDateOrContractMonth?.replace(/\D/g, "");
+  if (!date || date.length !== 8 || !contract.right || contract.strike === undefined) return null;
+  return `${contract.symbol.trim().toUpperCase()}|${date}|${contract.right}|${contract.strike}`;
+}
+
 export interface ResolvedOptionsTarget {
   isOptionTicker: boolean;
   parsedOption: ReturnType<typeof parseOptionSymbol>;
@@ -53,7 +98,7 @@ export function resolveOptionsTarget(ticker: TickerRecord | null | undefined): R
   if (!ticker) return null;
 
   const isOptionTicker = ticker.metadata.assetCategory === "OPT";
-  const parsedOption = isOptionTicker ? parseOptionSymbol(ticker.metadata.ticker) : null;
+  const parsedOption = isOptionTicker ? parseOptionTicker(ticker.metadata.ticker) : null;
   const effectiveTicker = parsedOption?.underlying ?? ticker.metadata.ticker;
 
   if (!effectiveTicker) return null;

package/src/utils/price-history.ts

@@ -7,6 +7,7 @@ import { zonedDateTimeParts } from "./zoned-date-time";
 import { regularHistorySessionStaleness } from "../market-data/history-session";
 import type { HistorySession } from "../types/price-history";
 import { BAR_INTERVAL_UNIT_MS, parseBarInterval } from "../time-series/resolution";
+import { parseOptionTicker } from "./options";
 
 // A venue without session hours here (OTC Markets, Cboe Canada) has no
 // session to hold: its copy is current while the latest bar is this recent.
@@ -217,6 +218,9 @@ export function isPriceHistoryStaleForCurrentWindow(
   // Daily/weekly/monthly labels are period starts, not live observation times.
   // Their cache policy controls refresh; an intraday lag test is inapplicable.
   if (intervalMs != null && intervalMs >= DAY_MS) return false;
+  // An option contract can go hours without a trade, so its last bar's age says nothing of
+  // its source; judged on it, a contract quiet since the open had no chart at all.
+  if (options.symbol && parseOptionTicker(options.symbol)) return false;
 
   const latestTime = getPricePointTimestamp(latest);
   if (!Number.isFinite(latestTime)) return false;

package/src/utils/reported-money.ts

@@ -1,5 +1,5 @@
 import { resolveCurrencyUnit } from "./currency-units";
-import { formatCompact, formatCurrency, formatNumber } from "./format";
+import { formatCompact, formatCurrency, formatCurrencyCode, formatNumber } from "./format";
 
 function perShareDecimals(value: number): number {
   const magnitude = Math.abs(value);
@@ -17,15 +17,19 @@ export function formatPerShareNumber(value: number | undefined): string {
   return formatNumber(value === 0 ? 0 : value, perShareDecimals(value)).replace(/(\.\d{2}.*?)0+$/, "$1");
 }
 
-/** Keep reported monetary amounts in their own units, independently of a quote. */
-export function formatReportedMoney(value: number | undefined, currency?: string, perShare = false): string {
+/**
+ * Keep reported monetary amounts in their own units, independently of a
+ * quote. A per-share amount reads with its sign ($6.54), or with `code` its
+ * code (6.54 USD) as every other amount does.
+ */
+export function formatReportedMoney(value: number | undefined, currency?: string, perShare = false, code = false): string {
   if (value == null || !Number.isFinite(value)) return "—";
   const amount = perShare ? formatPerShareNumber(value) : formatCompact(value);
   const unit = currency?.trim();
   if (!unit) return `${amount} (ccy?)`;
   // Intl uppercases currency codes: GBp must not become GBP without scaling.
   if (perShare && !usesScientificNotation(value) && /^[a-z]{3}$/i.test(unit) && resolveCurrencyUnit(unit).divisor === 1) {
-    return formatCurrency(value === 0 ? 0 : value, unit, perShareDecimals(value));
+    return (code ? formatCurrencyCode : formatCurrency)(value === 0 ? 0 : value, unit, perShareDecimals(value));
   }
   return `${amount} ${unit}`;
 }