gloomberb 0.17.2 → 0.17.3

package/src/plugins/builtin/research/relative-valuation-currency.ts

@@ -0,0 +1,164 @@
+import type { HeadlessPaneContext } from "../../../types/headless";
+import { MarketDataCoordinator, resolveEntryValue } from "../../../market-data/coordinator";
+import { fxLegForCurrency } from "../../../market-data/coordinator/fx-legs";
+import { resolveCurrencyUnit } from "../../../utils/currency-units";
+import { errorMessage } from "../../../utils/errors";
+
+/** One currency's US dollar rate, as the app's FX rates serve it: USD per unit, and when it was observed. */
+export interface UsdRate {
+  rate: number;
+  /** The source's observation time; null when it states none. */
+  asOf: string | null;
+  /** When the rate was read, said in place of an observation time the source does not state. */
+  retrievedAt?: string | null;
+}
+
+/** A rate a market cap was converted at: `to` per `from`, and the older of its two legs' observation times. */
+export interface CapConversion {
+  from: string;
+  to: string;
+  rate: number;
+  asOf: string | null;
+  /** When the rate was read, for a rate whose source states no observation time. */
+  retrievedAt: string | null;
+}
+
+type CapRow = { symbol: string; marketCap: number | null; marketCapCurrency: string | null };
+
+export type ConvertedCapRow<Row extends CapRow> = Row & {
+  /** The cap as the source served it, and its currency, when it was converted. */
+  marketCapNative?: number;
+  marketCapNativeCurrency?: string;
+};
+
+const usable = (rate: number | undefined): rate is number => rate != null && Number.isFinite(rate) && rate > 0;
+
+function olderOf(left: string | null, right: string | null): string | null {
+  if (!left || !right) return left ?? right;
+  return Date.parse(left) <= Date.parse(right) ? left : right;
+}
+
+/**
+ * Every row's market cap in `target`, through each currency's US dollar
+ * rate (a pence cap is first made pounds). A row already in `target`, or
+ * with no cap, stays as it is. A currency with no usable rate leaves its
+ * rows in their own currency and is listed in `unconverted`, so the table
+ * never mixes a guess in.
+ */
+export function convertMarketCaps<Row extends CapRow>(
+  rows: readonly Row[],
+  target: string,
+  rates: ReadonlyMap<string, UsdRate>,
+): { rows: Array<ConvertedCapRow<Row>>; conversions: CapConversion[]; unconverted: Array<{ currency: string; symbols: string[] }> } {
+  const usd = (currency: string): UsdRate | undefined => (currency === "USD" ? { rate: 1, asOf: null } : rates.get(currency));
+  const conversions = new Map<string, CapConversion>();
+  const unconverted = new Map<string, string[]>();
+  const converted = rows.map((row): ConvertedCapRow<Row> => {
+    if (row.marketCap == null || !row.marketCapCurrency || row.marketCapCurrency === target) return row;
+    const unit = resolveCurrencyUnit(row.marketCapCurrency);
+    let rate = 1;
+    if (unit.currency !== target) {
+      const from = usd(unit.currency);
+      const to = usd(target);
+      if (!from || !to || !usable(from.rate) || !usable(to.rate)) {
+        unconverted.set(row.marketCapCurrency, [...unconverted.get(row.marketCapCurrency) ?? [], row.symbol]);
+        return row;
+      }
+      rate = from.rate / to.rate;
+      if (!conversions.has(unit.currency)) {
+        conversions.set(unit.currency, {
+          from: unit.currency, to: target, rate, asOf: olderOf(from.asOf, to.asOf), retrievedAt: olderOf(from.retrievedAt ?? null, to.retrievedAt ?? null),
+        });
+      }
+    }
+    return {
+      ...row,
+      marketCap: row.marketCap / unit.divisor * rate,
+      marketCapCurrency: target,
+      marketCapNative: row.marketCap,
+      marketCapNativeCurrency: row.marketCapCurrency,
+    };
+  });
+  return {
+    rows: converted,
+    conversions: [...conversions.values()],
+    unconverted: [...unconverted].map(([currency, symbols]) => ({ currency, symbols })),
+  };
+}
+
+/** A rate as a dealer quotes it: `EUR/USD 1.1612`, `USD/JPY 151.20`; a cross of two other currencies as `from/to`. */
+export function conversionPairText({ from, to, rate }: Pick<CapConversion, "from" | "to" | "rate">): string {
+  const figure = (value: number) => value.toPrecision(5);
+  if (from !== "USD" && to !== "USD") return `${from}/${to} ${figure(rate)}`;
+  const other = to === "USD" ? from : to;
+  const usdPerOther = to === "USD" ? rate : 1 / rate;
+  const perDollar = fxLegForCurrency(other)?.invert ?? true;
+  return perDollar ? `USD/${other} ${figure(1 / usdPerOther)}` : `${other}/USD ${figure(usdPerOther)}`;
+}
+
+/** `2026-10-13 21:00 UTC`, or `2026-10-13` for a date. */
+function rateTimeText(asOf: string): string {
+  const time = Date.parse(asOf);
+  if (!Number.isFinite(time)) return asOf;
+  return /^\d{4}-\d{2}-\d{2}$/.test(asOf) ? asOf : `${new Date(time).toISOString().slice(0, 16).replace("T", " ")} UTC`;
+}
+
+/**
+ * The status line's note naming each rate and its date:
+ * `market caps in USD at EUR/USD 1.1612 (2026-10-13 21:00 UTC)`.
+ */
+export function conversionNote(target: string, conversions: readonly CapConversion[]): string | null {
+  if (conversions.length === 0) return null;
+  const rates = conversions.map((conversion) => `${conversionPairText(conversion)} (${conversion.asOf ? rateTimeText(conversion.asOf)
+    : conversion.retrievedAt ? `retrieved ${rateTimeText(conversion.retrievedAt)}` : "time not stated"})`);
+  return `market caps in ${target} at ${rates.join(", ")}`;
+}
+
+/**
+ * The US dollar rate of each currency through the app's FX path (the market
+ * data coordinator's `loadFxRate`, which converted totals read), a pence code
+ * as its pound. A currency whose rate fails is listed in `failed` with why.
+ */
+export async function loadFxLegs(
+  currencies: readonly string[],
+  ctx: Pick<HeadlessPaneContext, "marketData">,
+): Promise<{ legs: Map<string, UsdRate>; failed: Array<{ currency: string; reason: string }> }> {
+  const wanted = [...new Set(currencies.map((currency) => resolveCurrencyUnit(currency).currency).filter((currency) => currency && currency !== "USD"))];
+  const legs = new Map<string, UsdRate>();
+  const failed: Array<{ currency: string; reason: string }> = [];
+  if (wanted.length === 0) return { legs, failed };
+  const coordinator = new MarketDataCoordinator(ctx.marketData);
+  try {
+    await Promise.all(wanted.map(async (currency) => {
+      try {
+        const entry = await coordinator.loadFxRate(currency);
+        const rate = resolveEntryValue(entry);
+        if (!usable(rate ?? undefined)) throw new Error(entry.error?.message ?? "no usable rate");
+        const time = (value: number | null | undefined) => (value != null && Number.isFinite(value) ? new Date(value).toISOString() : null);
+        legs.set(currency, { rate: rate!, asOf: time(entry.asOf), retrievedAt: time(entry.fetchedAt) });
+      } catch (error) {
+        failed.push({ currency, reason: errorMessage(error) });
+      }
+    }));
+  } finally {
+    coordinator.destroy();
+  }
+  return { legs, failed };
+}
+
+const CURRENCY_CODE = /^[A-Z]{3}$/;
+
+/** `--currency`: a three-letter code the runtime knows, upper-cased. */
+export function normalizeCapCurrency(value: string): string {
+  const code = value.trim().toUpperCase();
+  let known: readonly string[] = [];
+  try {
+    known = Intl.supportedValuesOf("currency");
+  } catch {
+    // An older runtime lists none; the shape check stands alone.
+  }
+  if (!CURRENCY_CODE.test(code) || (known.length > 0 && !known.includes(code))) {
+    throw new Error(`Invalid --currency value "${value}". Use a three-letter currency code such as USD or EUR.`);
+  }
+  return code;
+}

package/src/plugins/builtin/research/relative-valuation-headless.ts

@@ -1,11 +1,16 @@
 import { formatPriceEarnings, NOT_MEANINGFUL, PRICE_EARNINGS_NOTICE } from "../../../utils/price-earnings";
-import type { HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/headless";
+import type { HeadlessPaneColumn, HeadlessPaneContext, HeadlessPaneDefinition } from "../../../types/headless";
 import { EXTENDED_SESSION_LABELS, type ExtendedSession } from "../../../market-data/market/status";
 import { formatCompact, formatCurrency, formatLevelPercent, formatNumber, formatPercent, formatPercentRaw } from "../../../utils/format";
 import { loadHeadlessFinancials, loadHeadlessSymbols } from "../shared/headless-market-data";
 import { quoteFreshnessFields } from "../shared/report-freshness";
 import { RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE, RELATIVE_VALUATION_STALE_QUOTE_NOTICE, relativeValuationValues } from "./relative-valuation-model";
 import { paneSchemas } from "./headless-schema";
+import { isRecord } from "../../../utils/guards";
+import { resolveCurrencyUnit } from "../../../utils/currency-units";
+import { pickPeers, peerMethodTitle, type PeerSelection } from "./relative-valuation-peers";
+import { extraColumns, loadExtraColumns, parseExtraColumns } from "./relative-valuation-columns";
+import { conversionNote, convertMarketCaps, loadFxLegs } from "./relative-valuation-currency";
 
 const price = (value: unknown, row: Record<string, unknown>) => (
   value == null || !row.currency ? "-" : formatCurrency(Number(value), String(row.currency))
@@ -46,7 +51,9 @@ const VALUATION_COLUMNS: HeadlessPaneColumn[] = [
   })),
   ...[["evSales", "EV/S"]].map(([key, header]) => ({
     key: key!, header: header!, align: "right" as const,
-    format: (value: unknown) => value == null ? "-" : formatNumber(Number(value), 1),
+    // A withdrawn EV says so rather than leaving a bare dash; the note under the table says why.
+    format: (value: unknown, row: Record<string, unknown>) => value != null ? formatNumber(Number(value), 1)
+      : row.evSalesUnavailable ? "EV unavailable" : "-",
   })),
   ...[["fcfYield", "FCF Yield"], ["revenueGrowth", "Quarter Revenue YoY"], ["operatingMargin", "TTM Op Margin"]].map(([key, header]) => ({
     key: key!, header: header!, align: "right" as const,
@@ -54,36 +61,112 @@ const VALUATION_COLUMNS: HeadlessPaneColumn[] = [
   })),
 ];
 
+/** Peers `--peers` chose, as the expansion left them in the settings or the load picked them. */
+function peerSelectionOf(value: unknown, symbols: readonly string[]): PeerSelection | null {
+  if (!isRecord(value) || typeof value.subject !== "string" || !Array.isArray(value.peers)) return null;
+  const selection = value as unknown as PeerSelection;
+  const expected = [selection.subject, ...selection.peers];
+  return expected.length === symbols.length && expected.every((symbol, index) => symbol.toUpperCase() === symbols[index]?.toUpperCase())
+    ? selection : null;
+}
+
+/** The peers of the one symbol `--peers` was given; several symbols are already a peer list. */
+async function choosePeers(symbols: readonly string[], ctx: HeadlessPaneContext): Promise<PeerSelection> {
+  if (symbols.length !== 1) {
+    throw new Error(`--peers picks the peers of one symbol, such as RV ${symbols[0] ?? "DUOL"} --peers; with several symbols, leave it out.`);
+  }
+  const subject = symbols[0]!;
+  return pickPeers(subject, await loadHeadlessFinancials(ctx, subject).catch(() => null), ctx);
+}
+
+const PEER_SELECTION_SETTING = "peerSelection";
+
 export const relativeValuationHeadless: HeadlessPaneDefinition<"rows"> = {
   ...paneSchemas["relative-valuation-pane"],
+  freshness: { datesEachVenue: true },
   shape: "rows",
-  describe: ({ symbols }) => `Relative Valuation | ${symbols.join(", ")}`,
+  describe: ({ symbols }, result) => {
+    const selection = peerSelectionOf(result?.metadata?.peerSelection, result?.symbols ?? symbols);
+    return selection
+      ? `Relative Valuation | ${selection.subject} and ${peerMethodTitle(selection)}`
+      : `Relative Valuation | ${(result?.symbols ?? symbols).join(", ")}`;
+  },
   columns: [...QUOTE_COLUMNS, ...VALUATION_COLUMNS],
-  async load({ symbols }, ctx) {
+  async expandArgument(args, ctx) {
+    if (args.options.peers !== true) return null;
+    const selection = await choosePeers(args.symbols, ctx);
+    return {
+      argument: [selection.subject, ...selection.peers].join(", "),
+      settings: { [PEER_SELECTION_SETTING]: selection },
+      title: `RV ${selection.subject} + ${peerMethodTitle(selection, { automatic: true })}`,
+    };
+  },
+  async load(args, ctx) {
+    // --peers picked in advance (fn and shot) reads the same peers; any other caller picks them here.
+    const preset = args.options.peers === true ? peerSelectionOf(ctx.settings?.[PEER_SELECTION_SETTING], args.symbols) : null;
+    const selection = args.options.peers === true ? preset ?? await choosePeers(args.symbols, ctx) : null;
+    const symbols = selection ? [selection.subject, ...selection.peers] : args.symbols;
     const loaded = await loadHeadlessSymbols(symbols, ctx, (symbol) => loadHeadlessFinancials(ctx, symbol));
-    const rows = loaded.entries.map(({ symbol, data }) => ({ symbol, ...relativeValuationValues(data), ...quoteFreshnessFields(data?.quote) }));
-    const unavailableSymbols = [...loaded.unavailableSymbols, ...rows.filter((row) => ![
+    const baseRows = loaded.entries.map(({ symbol, data }) => ({ symbol, ...relativeValuationValues(data), ...quoteFreshnessFields(data?.quote) }));
+    const unavailableSymbols = [...loaded.unavailableSymbols, ...baseRows.filter((row) => ![
       row.marketCap, row.trailingPE, row.forwardPE, row.evSales, row.fcfYield, row.revenueGrowth, row.operatingMargin,
     ].some((value) => value != null)).map(({ symbol }) => symbol)];
-    const staleSymbols = rows.filter((row) => row.quoteStale).map((row) => row.symbol);
-    const staleFundamentalsSymbols = rows.filter((row) => row.fundamentalsProvenance?.stale).map((row) => row.symbol);
+    const staleSymbols = baseRows.filter((row) => row.quoteStale).map((row) => row.symbol);
+    const staleFundamentalsSymbols = baseRows.filter((row) => row.fundamentalsProvenance?.stale).map((row) => row.symbol);
+
+    // --currency: every cap in one currency, at the rates the app converts with.
+    const capCurrency = typeof args.options.currency === "string" ? args.options.currency : null;
+    const fx = capCurrency ? await loadFxLegs([capCurrency, ...baseRows.flatMap((row) => row.marketCapCurrency ?? [])], ctx) : null;
+    const converted = capCurrency && fx ? convertMarketCaps(baseRows, capCurrency, fx.legs) : null;
+    const capRows = converted?.rows ?? baseRows;
+
+    // --columns: each added column read from the path its own function uses.
+    const extraIds = parseExtraColumns(args.options.columns);
+    const financials = new Map(loaded.entries.map(({ symbol, data }) => [symbol, data] as const));
+    const extra = await loadExtraColumns(extraIds, capRows.map((row) => row.symbol), financials, ctx);
+    const rows = capRows.map((row) => ({ ...row, ...extra.fields.get(row.symbol) }));
+
     const errors = [...loaded.errors,
       ...staleSymbols.map((symbol) => `${symbol}: ${RELATIVE_VALUATION_STALE_QUOTE_NOTICE}`),
       ...staleFundamentalsSymbols.map((symbol) => `${symbol}: ${RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE}`),
+      ...extra.errors,
+    ];
+    const warnings = converted?.unconverted.map(({ currency, symbols: left }) => {
+      const reason = fx?.failed.find((failure) => failure.currency === resolveCurrencyUnit(currency).currency)?.reason;
+      return `No ${currency} rate${reason ? ` (${reason})` : ""}: ${left.join(", ")} ${left.length === 1 ? "keeps its" : "keep their"} market cap in ${currency}.`;
+    }) ?? [];
+    const conversionText = capCurrency && converted ? conversionNote(capCurrency, converted.conversions) : null;
+    const notes = [
+      ...selection ? [`Peers chosen automatically: ${selection.basis}. To choose your own: gloomberb fn RV ${selection.subject} <tickers>.`] : [],
+      ...extra.notes,
     ];
     // Last and Chg% are the regular session; an extended print gets a column only when a peer has one.
     const extendedSessions = (["PRE", "POST", "OVERNIGHT"] as const).filter((session) => rows.some((row) => row.extendedSession === session));
+    const columns = [...QUOTE_COLUMNS, ...extendedSessions.map(extendedColumn), ...VALUATION_COLUMNS];
+    const added = extraIds.length > 0 ? extraColumns(extraIds) : null;
     return {
       rows, unavailableSymbols, errors, complete: unavailableSymbols.length === 0 && errors.length === 0,
-      ...(extendedSessions.length > 0 ? { columns: [...QUOTE_COLUMNS, ...extendedSessions.map(extendedColumn), ...VALUATION_COLUMNS] } : {}),
+      ...(selection ? { symbols } : {}),
+      ...(added ? { columns: [...columns, ...added.export], textColumns: [...columns, ...added.text] }
+        : extendedSessions.length > 0 ? { columns } : {}),
+      ...(notes.length > 0 ? { notes } : {}),
+      ...(warnings.length > 0 ? { warnings } : {}),
+      ...(conversionText ? { freshness: { note: conversionText } } : {}),
       metadata: {
         staleSymbols,
         staleFundamentalsSymbols,
+        ...(selection ? { peerSelection: selection } : {}),
+        ...(converted && capCurrency ? { marketCapConversion: { currency: capCurrency, rates: converted.conversions,
+          basis: "marketCap is converted into the asked currency at each currency's US dollar rate, the rate the app's converted totals use; marketCapNative and marketCapNativeCurrency keep the cap as served." } } : {}),
+        ...(extraIds.length > 0 ? { addedColumnsBasis: "Each added column keeps its own source and as-of beside it: short interest at its FINRA settlement date, analyst targets at retrieval, the next earnings date at the calendar's retrieval, gross margin and EV/EBITDA at the screener's statement date." } : {}),
         quoteBasis: "Stale quote fields are excluded from comparison; reportedQuote retains the rejected observation and quoteAsOf retains its source timestamp.",
         priceBasis: "price, change and changePercent are the regular session: after the close, its close and that close's move. A pre-market, after-hours or overnight print is in extendedPrice, extendedChange and extendedChangePercent, measured from that close (extendedMark when it is a bid and ask midpoint). marketCap, the P/E multiples, evSales (through the equity part of the enterprise value) and fcfYield are measured at that regular session price.",
         fundamentalsBasis: "Provider multiples and operating metrics retain independent fundamentalsProvenance. Retrieval time does not establish the valuation date.",
-        notices: rows.some((row) => Object.keys(row.notMeaningful).length > 0
-          || Object.values(row.reportedMultiples).some((value) => value != null && value <= 0)) ? [PRICE_EARNINGS_NOTICE] : [],
+        notices: [
+          ...rows.some((row) => Object.keys(row.notMeaningful).length > 0
+            || Object.values(row.reportedMultiples).some((value) => value != null && value <= 0)) ? [PRICE_EARNINGS_NOTICE] : [],
+          ...rows.flatMap((row) => row.evSalesUnavailable ? [`${row.symbol}: ${row.evSalesUnavailable}`] : []),
+        ],
         multipleBasis: "Comparable P/E fields require a positive finite multiple over positive EPS; notMeaningful says why one is null, and reportedMultiples preserves the finite provider values.",
         marketCapBasis: "Market caps retain their own currency and source. Fundamentals retrieval time is not a valuation date; quote timestamps do not date fallback caps.",
       },

package/src/plugins/builtin/research/relative-valuation-model.ts

@@ -1,6 +1,6 @@
 import { comparablePriceEarnings, notMeaningfulMultiples } from "../../../utils/price-earnings";
 import { selectMarketCapitalization } from "../../../utils/market-capitalization";
-import { reportedEnterpriseValue } from "../../../utils/fundamentals";
+import { enterpriseValueReconciliationNote, enterpriseValueWithdrawn, reportedEnterpriseValue } from "../../../utils/fundamentals";
 import { getExtendedSessionDisplay, getQuoteSessionFields } from "../../../market-data/market/status";
 import { atRegularSessionPrice, movePriceDerivedFigures } from "../../../market-data/quotes/regular-session-valuation";
 import type { Quote, TickerFinancials } from "../../../types/financials";
@@ -70,6 +70,9 @@ export function relativeValuationValues(snapshot: TickerFinancials | null) {
         ? fundamentals.enterpriseToRevenue
         : enterpriseValue != null && fundamentals?.revenue != null && fundamentals.revenue > 0
           ? enterpriseValue / fundamentals.revenue : null,
+    /** Why EV/S is missing when the provider's EV was withdrawn, as `valuation` says it; null otherwise. */
+    evSalesUnavailable: enterpriseValueWithdrawn(fundamentals)
+      ? enterpriseValueReconciliationNote(fundamentals) ?? "EV unavailable." : null,
     fcfYield: capitalization && fundamentals?.financialCurrency === capitalization.currency
       && fundamentals.freeCashFlow != null && Number.isFinite(fundamentals.freeCashFlow) && capitalization.value > 0
       ? fundamentals.freeCashFlow / capitalization.value : null,

package/src/plugins/builtin/research/relative-valuation-pane.tsx

@@ -159,7 +159,10 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
   const error = symbols.length > 0 ? peerSnapshot.error : "No tickers selected";
   const [selectedIdx, setSelectedIdx] = useState(0);
   const [sortPreference, setSortPreference] = useState<RelativeSortPreference>(DEFAULT_RELATIVE_SORT);
-  const baseCurrency = useAppSelector((state) => state.config.baseCurrency);
+  const appBaseCurrency = useAppSelector((state) => state.config.baseCurrency);
+  // `--currency` on a capture asks for another currency than the app's.
+  const capCurrency = typeof pane?.settings?.capCurrency === "string" ? pane.settings.capCurrency : null;
+  const baseCurrency = capCurrency ?? appBaseCurrency;
   const quoteTargets = useMemo<QuoteSubscriptionTarget[]>(() => symbols.map((peer) => ({
     symbol: peer,
     exchange: "",
@@ -209,8 +212,11 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
 
   usePaneNoticeFooter({
     registrationId: "relative-valuation-notices",
-    notices: rows.filter((row) => row.fundamentalsProvenance?.stale)
-      .map((row) => `${row.symbol}: ${RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE}.`),
+    notices: [
+      ...rows.filter((row) => row.fundamentalsProvenance?.stale)
+        .map((row) => `${row.symbol}: ${RELATIVE_VALUATION_STALE_FUNDAMENTALS_NOTICE}.`),
+      ...rows.flatMap((row) => row.evSalesUnavailable ? [`${row.symbol}: ${row.evSalesUnavailable}`] : []),
+    ],
     focused,
   });
 
@@ -237,7 +243,10 @@ export function RelativeValuationPane({ focused, width, height }: PaneProps) {
       case "forwardPE":
         return { text: formatPriceEarnings(row.notMeaningful.forwardPE ? NOT_MEANINGFUL : row.reportedMultiples.forwardPE), color: colors.text };
       case "evSales":
-        return { text: formatNumber(row.evSales ?? undefined, 1), color: colors.text };
+        // A withdrawn EV says so; the footer says why.
+        return row.evSales == null && row.evSalesUnavailable
+          ? { text: "EV n/a", color: colors.textDim }
+          : { text: formatNumber(row.evSales ?? undefined, 1), color: colors.text };
       case "fcfYield":
         return { text: formatLevelPercent(row.fcfYield ?? undefined), color: priceColor(row.fcfYield ?? 0) };
       case "revenueGrowth":