gloomberb 0.11.2 → 0.12.0

package/src/plugins/builtin/market-valuation/chart-projection.ts

@@ -0,0 +1,217 @@
+import type { ProjectedChartPoint } from "../../../components/chart/core/data";
+import { blendHex, colors } from "../../../theme/colors";
+import type { RatioPoint } from "./align";
+import type { ResolvedSeries, TimeSeriesPoint } from "../../../time-series/types";
+import {
+  classifyZone,
+  shortZoneLabel,
+  zoneColor,
+  type IndicatorDef,
+  type ValuationZoneId,
+} from "./defs";
+
+export interface ChartMarkerLine {
+  value: number;
+  label: string;
+}
+
+interface ChartReferenceLine {
+  value: number;
+  color: string;
+}
+
+export interface ValuationChartProjection {
+  points: ProjectedChartPoint[];
+  /** The ratio points behind the projection, for the interactive chart. */
+  sourcePoints: RatioPoint[];
+  referenceLines: ChartReferenceLine[];
+  yDomain: { min: number; max: number };
+  yearLabels: string[];
+  lineColors: string[];
+  /** Captions the pane positions against the plot; the renderer draws lines only. */
+  markers: ChartMarkerLine[];
+}
+
+/** Snaps to whole grid steps, and opens a floor when the measure can go negative. */
+export function niceDomain(
+  dataMin: number,
+  dataMax: number,
+  step: number,
+): { min: number; max: number } {
+  const span = step > 0 ? step : 1;
+  const hi = Number.isFinite(dataMax) && dataMax > 0 ? dataMax : 0;
+  const lo = Number.isFinite(dataMin) ? Math.min(0, dataMin) : 0;
+  return {
+    min: lo < 0 ? Math.floor(lo / span) * span : 0,
+    max: Math.max(span, Math.ceil(hi / span) * span),
+  };
+}
+
+export function meanRatio(points: readonly RatioPoint[]): number {
+  if (points.length === 0) return 0;
+  let total = 0;
+  for (const point of points) total += point.ratio;
+  return total / points.length;
+}
+
+/**
+ * @param visible points inside the selected range, which is what gets drawn
+ * @param mean full-history average, so the anchor does not move when the range changes
+ */
+export function projectChart(
+  indicator: IndicatorDef,
+  visible: readonly RatioPoint[],
+  mean: number,
+): ValuationChartProjection {
+  const points: ProjectedChartPoint[] = visible.map((p) => ({
+    date: new Date(p.date),
+    open: p.ratio,
+    high: p.ratio,
+    low: p.ratio,
+    close: p.ratio,
+    volume: 0,
+  }));
+
+  let yMax = -Infinity;
+  let yMin = Infinity;
+  for (const point of visible) {
+    yMax = Math.max(yMax, point.ratio);
+    yMin = Math.min(yMin, point.ratio);
+  }
+  if (!Number.isFinite(yMax)) yMax = 0;
+  if (!Number.isFinite(yMin)) yMin = 0;
+  if (indicator.reference) {
+    yMax = Math.max(yMax, indicator.reference.value);
+    yMin = Math.min(yMin, indicator.reference.value);
+  }
+  yMax = Math.max(yMax, mean);
+  yMin = Math.min(yMin, mean);
+
+  const markers: ChartMarkerLine[] = [];
+  const referenceLines: ChartReferenceLine[] = [];
+  if (indicator.reference) {
+    referenceLines.push({ value: indicator.reference.value, color: colors.textDim });
+    markers.push({ value: indicator.reference.value, label: indicator.reference.label });
+  }
+  if (Number.isFinite(mean)) {
+    referenceLines.push({ value: mean, color: blendHex(colors.textDim, colors.bg, 0.35) });
+    markers.push({ value: mean, label: "mean" });
+  }
+
+  return {
+    points,
+    sourcePoints: [...visible],
+    referenceLines,
+    yDomain: niceDomain(yMin, yMax, indicator.chartGridStep),
+    yearLabels: chartYearLabels(points),
+    lineColors: visible.map((point) => classifyZone(indicator, point.ratio).color),
+    markers,
+  };
+}
+
+export function chartYearLabels(points: readonly ProjectedChartPoint[], maxLabels = 8): string[] {
+  if (points.length === 0) return [];
+  const years: string[] = [];
+  for (const point of points) {
+    const year = String(point.date.getFullYear());
+    if (years[years.length - 1] !== year) years.push(year);
+  }
+  if (years.length <= maxLabels) return years;
+
+  const start = Number(years[0]);
+  const end = Number(years[years.length - 1]);
+  let step = 5;
+  while (Math.floor((end - start) / step) + 1 > maxLabels) {
+    step = step === 5 ? 10 : step * 2;
+    if (step > 100) break;
+  }
+
+  const picked: string[] = [years[0]!];
+  for (const year of years) {
+    if (Number(year) % step !== 0) continue;
+    if (picked[picked.length - 1] !== year) picked.push(year);
+  }
+  const last = years[years.length - 1]!;
+  if (picked[picked.length - 1] !== last) picked.push(last);
+  return picked;
+}
+
+/**
+ * CompositeChart draws one colour per series, so the zone gradient is carried by
+ * one series per zone that holds nulls everywhere the ratio sits in another band.
+ * A run keeps its neighbours' boundary points so the segments join without gaps.
+ */
+export function zoneSeriesFor(
+  indicator: IndicatorDef,
+  points: readonly RatioPoint[],
+): ResolvedSeries[] {
+  const byZone = new Map<ValuationZoneId, TimeSeriesPoint[]>();
+  const zones = points.map((point) => classifyZone(indicator, point.ratio));
+  for (const band of indicator.zones) {
+    if (!byZone.has(band.id)) byZone.set(band.id, []);
+  }
+
+  points.forEach((point, index) => {
+    const date = new Date(point.date);
+    const here = zones[index]!.id;
+    const before = zones[index - 1]?.id;
+    const after = zones[index + 1]?.id;
+    for (const [zoneId, series] of byZone) {
+      // Carry a boundary point into the neighbouring run so the line is continuous.
+      const belongs = zoneId === here || zoneId === before || zoneId === after;
+      series.push({ date, observedAt: date, value: belongs ? point.ratio : null });
+    }
+  });
+
+  const built: ResolvedSeries[] = [];
+  for (const [zoneId, series] of byZone) {
+    if (!series.some((entry) => entry.value != null)) continue;
+    built.push({
+      id: `zone:${zoneId}`,
+      label: shortZoneLabel(zoneId),
+      color: zoneColor(zoneId),
+      unit: indicator.axisUnit,
+      unitGroup: indicator.axisUnit === "%" ? "valuation-percent" : "valuation",
+      nativeFrequency: "daily",
+      dataShape: "scalar",
+      style: "line",
+      transform: "raw",
+      axis: "left",
+      panelId: "main",
+      interpolation: "none",
+      points: series,
+    });
+  }
+  return built;
+}
+
+/** Flat line at a fixed level, for parity, replacement cost, or the sample mean. */
+export function markerSeries(
+  indicator: IndicatorDef,
+  id: string,
+  label: string,
+  value: number,
+  color: string,
+  points: readonly RatioPoint[],
+): ResolvedSeries | null {
+  if (points.length === 0 || !Number.isFinite(value)) return null;
+  const ends = [points[0]!, points[points.length - 1]!].map((point) => {
+    const date = new Date(point.date);
+    return { date, observedAt: date, value };
+  });
+  return {
+    id,
+    label,
+    color,
+    unit: indicator.axisUnit,
+    unitGroup: indicator.axisUnit === "%" ? "valuation-percent" : "valuation",
+    nativeFrequency: "daily",
+    dataShape: "scalar",
+    style: "line",
+    transform: "raw",
+    axis: "left",
+    panelId: "main",
+    interpolation: "none",
+    points: ends,
+  };
+}

package/src/plugins/builtin/market-valuation/chart-series.ts

@@ -0,0 +1,89 @@
+import { chartSeriesProvider } from "../../../capabilities";
+import type { ChartSeriesCatalogItem, ChartSeriesCapability } from "../../../capabilities";
+import { colors } from "../../../theme/colors";
+import type { ResolvedSeries, TimeSeriesPoint } from "../../../time-series/types";
+import { buildValuationSeries } from "./align";
+import { defaultValuationSeriesLoader, type ValuationSeriesLoader } from "./client";
+import { indicatorSeries, type IndicatorDef } from "./defs";
+import { findIndicator, INDICATORS } from "./indicators";
+import type { DatedSeries } from "./series";
+
+export const MARKET_VALUATION_CAPABILITY_ID = "market-valuation";
+
+function catalogItem(indicator: IndicatorDef): ChartSeriesCatalogItem {
+  return {
+    seriesId: indicator.id,
+    label: indicator.label,
+    description: indicator.description,
+    detail: "Market valuation",
+    style: "line",
+  };
+}
+
+function matches(indicator: IndicatorDef, query: string): boolean {
+  const haystack = `${indicator.id} ${indicator.label} ${indicator.shortLabel} ${indicator.description}`;
+  return haystack.toLowerCase().includes(query);
+}
+
+/**
+ * A ratio is not a series anyone can fetch, so the pane's own computation is what
+ * makes it chartable. Exposing it here lets G overlay, say, the Buffett indicator
+ * against CPI without the pane being involved.
+ */
+export function createValuationChartSeriesCapability(
+  loader: ValuationSeriesLoader = defaultValuationSeriesLoader,
+): ChartSeriesCapability {
+  return chartSeriesProvider({
+    id: MARKET_VALUATION_CAPABILITY_ID,
+    name: "Market Valuation",
+    provider: {
+      catalog: ({ limit }) => INDICATORS.slice(0, limit ?? INDICATORS.length).map(catalogItem),
+      search: ({ query, limit }) => {
+        const needle = query?.trim().toLowerCase();
+        const hits = needle
+          ? INDICATORS.filter((indicator) => matches(indicator, needle))
+          : [...INDICATORS];
+        return hits.slice(0, limit ?? hits.length).map(catalogItem);
+      },
+      resolve: async ({ seriesId }) => resolveValuationSeries(seriesId, loader),
+    },
+  });
+}
+
+export async function resolveValuationSeries(
+  seriesId: string,
+  loader: ValuationSeriesLoader = defaultValuationSeriesLoader,
+): Promise<ResolvedSeries> {
+  const indicator = findIndicator(seriesId);
+  if (indicator.id !== seriesId.trim().toLowerCase()) {
+    throw new Error(`Unknown valuation series ${seriesId}`);
+  }
+
+  const legs = new Map<string, DatedSeries>();
+  await Promise.all(indicatorSeries(indicator).map(async (def) => {
+    legs.set(def.key, await loader(def));
+  }));
+
+  const built = buildValuationSeries(indicator, legs);
+  const points: TimeSeriesPoint[] = built.points.map((point) => {
+    const date = new Date(point.date);
+    return { date, observedAt: date, value: point.ratio };
+  });
+
+  return {
+    id: `market-valuation:${indicator.id}`,
+    label: indicator.label,
+    color: colors.textBright,
+    // Percent-scaled ratios share an axis with each other, never with a price.
+    unit: indicator.ratioScale === 100 ? "%" : "x",
+    unitGroup: indicator.ratioScale === 100 ? "valuation-percent" : "valuation-ratio",
+    nativeFrequency: "daily",
+    dataShape: "scalar",
+    style: "line",
+    transform: "raw",
+    axis: "left",
+    panelId: "main",
+    interpolation: "none",
+    points,
+  };
+}

package/src/plugins/builtin/market-valuation/client.test.ts

@@ -0,0 +1,141 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { MemoryPluginPersistence } from "../../../test-support/plugin-persistence";
+import { attachValuationPersistence, resetValuationPersistence } from "./cache";
+import { loadValuationBundle, requiredSeries, type ValuationSeriesLoader } from "./client";
+import { BUFFETT_INDICATOR, INDICATORS, SHILLER_CAPE, TOBINS_Q } from "./indicators";
+import type { DatedObservation, DatedSeries } from "./series";
+import { createSourceLoader, shillerObservations } from "./sources";
+
+function obs(values: Array<[string, number]>): DatedObservation[] {
+  return values.map(([date, value]) => ({ date, value }));
+}
+
+const LEGS: Record<string, DatedObservation[]> = {
+  W5000: obs([["2024-01-02", 40_000], ["2025-01-02", 45_000]]),
+  GDP: obs([["2024-01-01", 25_000], ["2025-01-01", 26_000]]),
+  M2SL: obs([["2024-01-01", 20_000], ["2025-01-01", 21_000]]),
+  NCBEILQ027S: obs([["2024-01-01", 60_000_000], ["2025-01-01", 64_000_000]]),
+  TNWMVBSNNCB: obs([["2024-01-01", 40_000_000], ["2025-01-01", 41_000_000]]),
+  BOGZ1FL153064486Q: obs([["2024-01-01", 38], ["2025-01-01", 45.8]]),
+  BOGZ1FL663067003Q: obs([["2024-01-01", 600000], ["2025-01-01", 650000]]),
+  CPROFIT: obs([["2024-01-01", 3400], ["2025-01-01", 4800]]),
+  SHILLER_CAPE: obs([["2024-01-01", 33.2], ["2025-01-01", 38.1]]),
+  SHILLER_ECY: obs([["2024-01-01", 0.021], ["2025-01-01", 0.013]]),
+  SHILLER_DIVIDEND: obs([["2024-01-01", 70], ["2025-01-01", 78]]),
+  SHILLER_PRICE: obs([["2024-01-01", 4800], ["2025-01-01", 6000]]),
+};
+
+const everyLeg: ValuationSeriesLoader = async (def) => {
+  const observations = LEGS[def.key];
+  if (!observations) throw new Error(`unexpected ${def.key}`);
+  return { seriesId: def.key, observations, provenance: "fred" } satisfies DatedSeries;
+};
+
+beforeEach(() => {
+  resetValuationPersistence();
+  attachValuationPersistence(new MemoryPluginPersistence());
+});
+afterEach(resetValuationPersistence);
+
+describe("requiredSeries", () => {
+  test("fetches a leg shared by two indicators only once", () => {
+    // Buffett and Cap/M2 share the Wilshire leg.
+    const keys = requiredSeries(INDICATORS).map((def) => def.key);
+    expect(keys.filter((key) => key === "W5000")).toHaveLength(1);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+});
+
+describe("loadValuationBundle", () => {
+  test("builds every registered indicator", async () => {
+    const bundle = await loadValuationBundle({ loader: everyLeg });
+    expect(bundle.builds.map((build) => build.indicator.id))
+      .toEqual(INDICATORS.map((indicator) => indicator.id));
+  });
+
+  test("one broken leg only drops the indicators that need it", async () => {
+    const bundle = await loadValuationBundle({
+      loader: async (def) => {
+        if (def.key === "W5000") throw new Error("history unavailable");
+        return everyLeg(def);
+      },
+    });
+    const ids = bundle.builds.map((build) => build.indicator.id);
+    expect(ids).not.toContain("buffett");
+    expect(ids).not.toContain("market-cap-m2");
+    expect(ids).toContain("shiller-cape");
+    expect(bundle.errors.join(" ")).toContain("W5000");
+  });
+
+  test("throws when nothing builds", async () => {
+    await expect(loadValuationBundle({
+      loader: async () => { throw new Error("offline"); },
+    })).rejects.toThrow("offline");
+  });
+});
+
+describe("createSourceLoader", () => {
+  test("fetches the Shiller dataset once for every column that needs it", async () => {
+    let shillerCalls = 0;
+    const loader = createSourceLoader({
+      loadFred: async () => obs([["2024-01-01", 1]]),
+      loadMarketHistory: async () => obs([["2024-01-01", 1]]),
+      loadShiller: async () => {
+        shillerCalls += 1;
+        return {
+          observations: [
+            { date: "2026-08-01", price: 7600, dividend: 81, earnings: null, cpi: 333, longRate: 4.75, cape: 41.2, excessCapeYield: 0.0097 },
+          ],
+          sourceUrl: "https://example.test/ie_data.xls",
+          fetchedAt: "2026-09-02T00:00:00.000Z",
+        };
+      },
+    });
+
+    const shillerLegs = requiredSeries(INDICATORS)
+      .filter((def) => def.source.kind === "shiller");
+    expect(shillerLegs.length).toBeGreaterThan(1);
+    const loaded = await Promise.all(shillerLegs.map((def) => loader(def)));
+    expect(shillerCalls).toBe(1);
+    expect(loaded.every((entry) => entry.observations.length === 1)).toBe(true);
+  });
+
+  test("routes each source kind to its own transport", async () => {
+    const seen: string[] = [];
+    const loader = createSourceLoader({
+      loadFred: async (seriesId) => { seen.push(`fred:${seriesId}`); return obs([["2024-01-01", 1]]); },
+      loadMarketHistory: async (symbol) => { seen.push(`history:${symbol}`); return obs([["2024-01-01", 1]]); },
+      loadShiller: async () => { throw new Error("not needed"); },
+    });
+    if (BUFFETT_INDICATOR.input.kind !== "ratio") throw new Error("expected a ratio");
+    await loader(BUFFETT_INDICATOR.input.numerator);
+    await loader(BUFFETT_INDICATOR.input.denominator);
+    if (TOBINS_Q.input.kind !== "ratio") throw new Error("expected a ratio");
+    await loader(TOBINS_Q.input.numerator);
+    expect(seen).toEqual(["history:^W5000", "fred:GDP", "fred:NCBEILQ027S"]);
+  });
+});
+
+describe("shillerObservations", () => {
+  test("keeps a column's nulls rather than dropping the month", () => {
+    const observations = shillerObservations({
+      observations: [
+        { date: "2026-07-01", price: 7481, dividend: null, earnings: null, cpi: 333, longRate: 4.6, cape: 40.6, excessCapeYield: 0.0118 },
+        { date: "2026-08-01", price: 7600, dividend: 81, earnings: null, cpi: 333, longRate: 4.75, cape: 41.2, excessCapeYield: 0.0097 },
+      ],
+      sourceUrl: "x",
+      fetchedAt: "y",
+    }, "dividend");
+    expect(observations.map((entry) => entry.value)).toEqual([null, 81]);
+  });
+
+  test("throws when a column is entirely empty", () => {
+    expect(() => shillerObservations({
+      observations: [
+        { date: "2026-08-01", price: 7600, dividend: null, earnings: null, cpi: null, longRate: null, cape: null, excessCapeYield: null },
+      ],
+      sourceUrl: "x",
+      fetchedAt: "y",
+    }, "earnings")).toThrow("no earnings observations");
+  });
+});

package/src/plugins/builtin/market-valuation/client.ts

@@ -0,0 +1,116 @@
+import { buildValuationSeries } from "./align";
+import { getCachedSeries, loadCachedSeries } from "./cache";
+import { indicatorSeries, type IndicatorDef, type SeriesDef } from "./defs";
+import { INDICATORS } from "./indicators";
+import type { DatedSeries } from "./series";
+import {
+  cloudSourceDeps,
+  createSourceLoader,
+  provenanceFor,
+  type ValuationSourceDeps,
+} from "./sources";
+import { fitIndicatorTrend } from "./trend";
+import type { IndicatorBuild, ValuationBundle } from "./view";
+
+export type ValuationSeriesLoader = (def: SeriesDef) => Promise<DatedSeries>;
+
+/** Every distinct leg the registry needs, so shared series are fetched once. */
+export function requiredSeries(
+  indicators: readonly IndicatorDef[] = INDICATORS,
+): SeriesDef[] {
+  const seen = new Map<string, SeriesDef>();
+  for (const indicator of indicators) {
+    for (const def of indicatorSeries(indicator)) {
+      if (!seen.has(def.key)) seen.set(def.key, def);
+    }
+  }
+  return [...seen.values()];
+}
+
+/** Cache-first around the cloud sources; exported so Bun-side tooling can reuse it. */
+export function createValuationSeriesLoader(deps: ValuationSourceDeps): ValuationSeriesLoader {
+  const cloudLoader = createSourceLoader(deps);
+  return async (def) => ({
+    seriesId: def.key,
+    observations: await loadCachedSeries(def.key, async () => (await cloudLoader(def)).observations),
+    provenance: provenanceFor(def),
+  });
+}
+
+export const defaultValuationSeriesLoader = createValuationSeriesLoader(cloudSourceDeps);
+
+/** Builds whatever the on-disk cache can already answer, for an instant first paint. */
+export function getCachedValuationBundle(
+  indicators: readonly IndicatorDef[] = INDICATORS,
+): ValuationBundle | null {
+  const legs = new Map<string, DatedSeries>();
+  for (const def of requiredSeries(indicators)) {
+    const cached = getCachedSeries(def.key, { allowExpired: true });
+    if (!cached) continue;
+    legs.set(def.key, {
+      seriesId: def.key,
+      observations: cached.observations,
+      provenance: provenanceFor(def),
+    });
+  }
+  const builds = buildIndicators(legs, [], indicators);
+  return builds.length > 0 ? { builds, errors: [], fetchedAt: Date.now() } : null;
+}
+
+function buildIndicators(
+  legs: Map<string, DatedSeries>,
+  errors: string[],
+  indicators: readonly IndicatorDef[],
+): IndicatorBuild[] {
+  const builds: IndicatorBuild[] = [];
+  for (const indicator of indicators) {
+    if (indicatorSeries(indicator).some((def) => !legs.has(def.key))) continue;
+    try {
+      const series = buildValuationSeries(indicator, legs);
+      builds.push({
+        indicator,
+        series,
+        trend: fitIndicatorTrend(indicator, series.points),
+      });
+    } catch (error) {
+      errors.push(`${indicator.label}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return builds;
+}
+
+function summarizeErrors(errors: readonly string[]): string {
+  if (errors.length === 0) return "Market valuation data unavailable";
+  const reasons = new Set(errors.map((entry) => entry.replace(/^[^:]+:\s*/, "")));
+  const reason = reasons.size === 1 ? [...reasons][0]! : `${errors.length} series failed`;
+  return errors.length > 1 ? `${reason} (${errors.length} series)` : reason;
+}
+
+export async function loadValuationBundle(options?: {
+  loader?: ValuationSeriesLoader;
+  indicators?: readonly IndicatorDef[];
+}): Promise<ValuationBundle> {
+  const loader = options?.loader ?? defaultValuationSeriesLoader;
+  const indicators = options?.indicators ?? INDICATORS;
+  const errors: string[] = [];
+  const legs = new Map<string, DatedSeries>();
+
+  const settled = await Promise.all(requiredSeries(indicators).map(async (def) => {
+    try {
+      return { def, data: await loader(def) };
+    } catch (error) {
+      return {
+        def,
+        error: `${def.key}: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }));
+  for (const outcome of settled) {
+    if ("error" in outcome && outcome.error) errors.push(outcome.error);
+    if ("data" in outcome && outcome.data) legs.set(outcome.def.key, outcome.data);
+  }
+
+  const builds = buildIndicators(legs, errors, indicators);
+  if (builds.length === 0) throw new Error(summarizeErrors(errors));
+  return { builds, errors, fetchedAt: Date.now() };
+}