gloomberb 0.1.0 → 0.3.1

package/src/utils/format.ts

@@ -0,0 +1,158 @@
+const currencyFormatters = new Map<string, Intl.NumberFormat>();
+const numberFormatters = new Map<number, Intl.NumberFormat>();
+
+function getCurrencyFormatter(currency: string): Intl.NumberFormat {
+  let formatter = currencyFormatters.get(currency);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat("en-US", {
+      style: "currency",
+      currency,
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2,
+    });
+    currencyFormatters.set(currency, formatter);
+  }
+  return formatter;
+}
+
+function getNumberFormatter(decimals: number): Intl.NumberFormat {
+  let formatter = numberFormatters.get(decimals);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat("en-US", {
+      minimumFractionDigits: decimals,
+      maximumFractionDigits: decimals,
+    });
+    numberFormatters.set(decimals, formatter);
+  }
+  return formatter;
+}
+
+/** Format a number as currency (e.g., $1,234.56) */
+export function formatCurrency(value: number | undefined, currency = "USD"): string {
+  if (value === undefined || value === null || Number.isNaN(value)) return "—";
+  return getCurrencyFormatter(currency).format(value);
+}
+
+/** Format a number as percentage (e.g., +1.23%) */
+export function formatPercent(value: number | undefined): string {
+  if (value === undefined || value === null) return "—";
+  const sign = value > 0 ? "+" : "";
+  return `${sign}${(value * 100).toFixed(2)}%`;
+}
+
+/** Format a percentage that's already in percent form (e.g., 1.23 -> +1.23%) */
+export function formatPercentRaw(value: number | undefined): string {
+  if (value === undefined || value === null) return "—";
+  const sign = value > 0 ? "+" : "";
+  return `${sign}${value.toFixed(2)}%`;
+}
+
+/** Format large numbers compactly (e.g., 1.5T, 234B, 12.3M, 5k) */
+export function formatCompact(value: number | undefined): string {
+  if (value === undefined || value === null) return "—";
+  const abs = Math.abs(value);
+  const sign = value < 0 ? "-" : "";
+  const fmt = (n: number, decimals: number, suffix: string) => {
+    const fixed = n.toFixed(decimals);
+    // Strip unnecessary trailing zeros after decimal point
+    const trimmed = fixed.includes(".") ? fixed.replace(/\.?0+$/, "") : fixed;
+    return `${sign}${trimmed}${suffix}`;
+  };
+  if (abs >= 1e12) return fmt(abs / 1e12, 2, "T");
+  if (abs >= 1e9) return fmt(abs / 1e9, 2, "B");
+  if (abs >= 1e6) return fmt(abs / 1e6, 2, "M");
+  if (abs >= 1e3) return fmt(abs / 1e3, 1, "k");
+  return fmt(abs, 2, "");
+}
+
+/** Format a compact value with an explicit currency code (e.g., 1.5T USD) */
+export function formatCompactCurrency(value: number | undefined, currency = "USD"): string {
+  if (value === undefined || value === null) return "—";
+  return `${formatCompact(value)} ${currency}`;
+}
+
+/** Format a plain number with commas */
+export function formatNumber(value: number | undefined, decimals = 2): string {
+  if (value === undefined || value === null) return "—";
+  return getNumberFormatter(decimals).format(value);
+}
+
+/** Format a price with commas, trimming unnecessary trailing zeros (e.g., 3,565.00 -> 3,565) */
+export function formatPrice(value: number | undefined): string {
+  if (value === undefined || value === null || Number.isNaN(value)) return "—";
+  const formatted = getNumberFormatter(2).format(value);
+  return formatted.replace(/\.00$/, "").replace(/(\.\d)0$/, "$1");
+}
+
+/** Format a growth rate compactly (e.g., +12%, -5%) */
+export function formatGrowthShort(value: number): string {
+  const pct = value * 100;
+  const sign = pct > 0 ? "+" : "";
+  return Math.abs(pct) >= 10
+    ? `${sign}${Math.round(pct)}%`
+    : `${sign}${pct.toFixed(1)}%`;
+}
+
+/** Pick a common unit suffix for a set of numbers */
+export function pickUnit(values: (number | undefined)[]): { suffix: string; divisor: number } {
+  const defined = values.filter((v): v is number => v != null);
+  if (!defined.length) return { suffix: "", divisor: 1 };
+  const maxAbs = Math.max(...defined.map(Math.abs));
+  if (maxAbs >= 1e12) return { suffix: "T", divisor: 1e12 };
+  if (maxAbs >= 1e9) return { suffix: "B", divisor: 1e9 };
+  if (maxAbs >= 1e6) return { suffix: "M", divisor: 1e6 };
+  if (maxAbs >= 1e3) return { suffix: "K", divisor: 1e3 };
+  return { suffix: "", divisor: 1 };
+}
+
+/** Format a number using a pre-determined divisor (no unit suffix) */
+export function formatWithDivisor(value: number | undefined, divisor: number): string {
+  if (value === undefined || value === null) return "—";
+  const scaled = value / divisor;
+  const abs = Math.abs(scaled);
+  const decimals = abs >= 100 ? 1 : 2;
+  return scaled.toFixed(decimals);
+}
+
+/** Pad/truncate a string to a fixed width */
+export function padTo(str: string, width: number, align: "left" | "right" | "center" = "left"): string {
+  if (str.length > width) return str.slice(0, width);
+  if (align === "right") return str.padStart(width);
+  if (align === "center") {
+    const totalPadding = width - str.length;
+    const leftPadding = Math.floor(totalPadding / 2);
+    const rightPadding = totalPadding - leftPadding;
+    return " ".repeat(leftPadding) + str + " ".repeat(rightPadding);
+  }
+  return str.padEnd(width);
+}
+
+/** Convert a value from one currency to base currency using cached exchange rates */
+export function convertCurrency(
+  value: number,
+  fromCurrency: string,
+  baseCurrency: string,
+  exchangeRates: Map<string, number>,
+): number {
+  if (fromCurrency === baseCurrency) return value;
+  const fromRate = exchangeRates.get(fromCurrency);
+  const baseRate = exchangeRates.get(baseCurrency);
+  if (fromRate == null || baseRate == null || baseRate === 0) return value;
+  return (value * fromRate) / baseRate;
+}
+
+/** Format a date/timestamp as relative time (e.g., "5m ago", "2h ago") */
+export function formatTimeAgo(date: Date | string): string {
+  const ts = typeof date === "string"
+    ? new Date(date.endsWith("Z") ? date : date + "Z").getTime()
+    : date.getTime();
+  const seconds = Math.floor((Date.now() - ts) / 1000);
+  if (seconds < 60) return "just now";
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d ago`;
+  return new Date(ts).toLocaleDateString("en-US", { month: "numeric", day: "numeric", year: "2-digit" });
+}

package/src/utils/fuzzy-search.ts

@@ -0,0 +1,34 @@
+/** Simple fuzzy matching: all query chars must appear in order in target */
+export function fuzzyMatch(query: string, target: string): { match: boolean; score: number } {
+  const q = query.toLowerCase();
+  const t = target.toLowerCase();
+
+  if (q.length === 0) return { match: true, score: 0 };
+  if (t.startsWith(q)) return { match: true, score: 1000 - q.length }; // exact prefix match
+  if (t.includes(q)) return { match: true, score: 500 - q.length }; // substring match
+
+  let qi = 0;
+  let score = 0;
+  for (let ti = 0; ti < t.length && qi < q.length; ti++) {
+    if (t[ti] === q[qi]) {
+      score += ti === 0 || t[ti - 1] === " " || t[ti - 1] === "-" ? 10 : 1;
+      qi++;
+    }
+  }
+
+  return { match: qi === q.length, score };
+}
+
+/** Filter and sort items by fuzzy match score */
+export function fuzzyFilter<T>(
+  items: T[],
+  query: string,
+  getText: (item: T) => string,
+): T[] {
+  if (!query) return items;
+  return items
+    .map((item) => ({ item, ...fuzzyMatch(query, getText(item)) }))
+    .filter((r) => r.match)
+    .sort((a, b) => b.score - a.score)
+    .map((r) => r.item);
+}

package/src/utils/market-status.ts

@@ -0,0 +1,95 @@
+import type { MarketState, Quote } from "../types/financials";
+import { colors, priceColor } from "../theme/colors";
+import { formatPercentRaw } from "./format";
+
+export interface ActiveQuoteDisplay {
+  price: number;
+  change: number;
+  changePercent: number;
+}
+
+export function marketStateLabel(state: MarketState): string {
+  switch (state) {
+    case "PRE": return "PRE-MKT";
+    case "REGULAR": return "OPEN";
+    case "POST": return "AFTER-HRS";
+    case "PREPRE":
+    case "POSTPOST":
+    case "CLOSED": return "CLOSED";
+  }
+}
+
+export function marketStateColor(state: MarketState): string {
+  switch (state) {
+    case "REGULAR": return colors.positive;
+    case "PRE":
+    case "POST": return colors.textBright;
+    case "PREPRE":
+    case "POSTPOST":
+    case "CLOSED": return colors.textDim;
+  }
+}
+
+/** Short exchange display name */
+export function exchangeShortName(exchangeName?: string, fullExchangeName?: string): string {
+  if (!exchangeName && !fullExchangeName) return "";
+  const name = exchangeName || fullExchangeName || "";
+  // Common Yahoo Finance exchange abbreviations
+  const map: Record<string, string> = {
+    NMS: "NASDAQ", NGM: "NASDAQ", NCM: "NASDAQ", NAS: "NASDAQ",
+    NYQ: "NYSE", NYS: "NYSE",
+    PCX: "AMEX", ASE: "AMEX",
+    HKG: "HKEX",
+    TYO: "TYO",
+    LSE: "LSE",
+    ASX: "ASX",
+    SGX: "SGX",
+    KSC: "KRX", KOE: "KOSDAQ",
+    TAI: "TWSE",
+    SHH: "SSE", SHZ: "SZSE",
+    PAR: "EURONEXT", AMS: "EURONEXT", BRU: "EURONEXT",
+    GER: "XETRA",
+    OSL: "OSE",
+    BOM: "BSE", NSI: "NSE",
+    SAO: "B3",
+    JPX: "TYO",
+  };
+  return map[name] || name;
+}
+
+/** Get extended hours price info (pre-market or after-hours) for display */
+export function getExtendedHoursInfo(quote: Quote | null | undefined): { text: string; color: string } | null {
+  if (!quote) return null;
+  if ((quote.marketState === "PRE" || quote.marketState === "PREPRE") && quote.preMarketPrice != null) {
+    const chg = quote.preMarketChangePercent ?? 0;
+    return { text: `Pre ${quote.preMarketPrice.toFixed(2)} ${formatPercentRaw(chg)}`, color: priceColor(chg) };
+  }
+  if ((quote.marketState === "POST" || quote.marketState === "POSTPOST") && quote.postMarketPrice != null) {
+    const chg = quote.postMarketChangePercent ?? 0;
+    return { text: `AH ${quote.postMarketPrice.toFixed(2)} ${formatPercentRaw(chg)}`, color: priceColor(chg) };
+  }
+  return null;
+}
+
+export function getActiveQuoteDisplay(quote: Quote | null | undefined): ActiveQuoteDisplay | null {
+  if (!quote) return null;
+  if ((quote.marketState === "PRE" || quote.marketState === "PREPRE") && quote.preMarketPrice != null) {
+    return {
+      price: quote.preMarketPrice,
+      change: quote.preMarketChange ?? 0,
+      changePercent: quote.preMarketChangePercent ?? 0,
+    };
+  }
+  if ((quote.marketState === "POST" || quote.marketState === "POSTPOST") && quote.postMarketPrice != null) {
+    return {
+      price: quote.postMarketPrice,
+      change: quote.postMarketChange ?? 0,
+      changePercent: quote.postMarketChangePercent ?? 0,
+    };
+  }
+  return {
+    price: quote.price,
+    change: quote.change,
+    changePercent: quote.changePercent,
+  };
+}

package/src/utils/options.ts

@@ -0,0 +1,86 @@
+import type { BrokerContractRef } from "../types/instrument";
+import type { TickerRecord } from "../types/ticker";
+
+export const MONTH_ABBREV = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/** Format a unix timestamp (seconds) as "Mon DD 'YY" */
+export function formatExpDate(ts: number): string {
+  const d = new Date(ts * 1000);
+  const month = MONTH_ABBREV[d.getMonth()] || String(d.getMonth() + 1);
+  const yy = String(d.getFullYear()).slice(2);
+  return `${month} ${d.getDate()} '${yy}`;
+}
+
+/**
+ * Parse IBKR option symbol like "UBER 260821C00090000" into components.
+ * Returns null if not a recognized option symbol.
+ */
+export function parseOptionSymbol(symbol: string): { underlying: string; expTs: number; strike: number; side: "C" | "P" } | null {
+  const m = symbol.match(/^(\S+)\s+(\d{2})(\d{2})(\d{2})([CP])(\d{8})$/);
+  if (!m) return null;
+  const [, underlying, yy, mm, dd, side, rawStrike] = m;
+  const strike = parseInt(rawStrike!, 10) / 1000;
+  const year = 2000 + parseInt(yy!, 10);
+  const month = parseInt(mm!, 10) - 1;
+  const day = parseInt(dd!, 10);
+  const expTs = Math.floor(new Date(year, month, day).getTime() / 1000);
+  return { underlying: underlying!, expTs, strike, side: side as "C" | "P" };
+}
+
+export interface ResolvedOptionsTarget {
+  isOptionTicker: boolean;
+  parsedOption: ReturnType<typeof parseOptionSymbol>;
+  effectiveTicker: string;
+  effectiveExchange: string;
+  instrument: BrokerContractRef | null;
+  cacheKey: string;
+}
+
+function buildOptionsCacheKey(
+  effectiveTicker: string,
+  effectiveExchange: string,
+  instrument: BrokerContractRef | null,
+): string {
+  return [
+    effectiveTicker.trim().toUpperCase(),
+    effectiveExchange.trim().toUpperCase(),
+    instrument?.brokerInstanceId ?? "",
+    instrument?.conId != null ? String(instrument.conId) : "",
+  ].join("|");
+}
+
+export function resolveOptionsTarget(ticker: TickerRecord | null | undefined): ResolvedOptionsTarget | null {
+  if (!ticker) return null;
+
+  const isOptionTicker = ticker.metadata.assetCategory === "OPT";
+  const parsedOption = isOptionTicker ? parseOptionSymbol(ticker.metadata.ticker) : null;
+  const effectiveTicker = parsedOption?.underlying ?? ticker.metadata.ticker;
+
+  if (!effectiveTicker) return null;
+
+  const effectiveExchange = isOptionTicker ? "" : (ticker.metadata.exchange ?? "");
+  const instrument = ticker.metadata.broker_contracts?.[0] ?? null;
+
+  return {
+    isOptionTicker,
+    parsedOption,
+    effectiveTicker,
+    effectiveExchange,
+    instrument,
+    cacheKey: buildOptionsCacheKey(effectiveTicker, effectiveExchange, instrument),
+  };
+}
+
+/**
+ * Format IBKR option symbol like "UBER 260821C00090000" into readable form.
+ * e.g. "UBER C $90 Aug'26"
+ */
+export function formatOptionTicker(symbol: string): string {
+  const m = symbol.match(/^(\S+)\s+(\d{2})(\d{2})(\d{2})([CP])(\d{8})$/);
+  if (!m) return symbol;
+  const [, underlying, yy, mm, , side, rawStrike] = m;
+  const strike = parseInt(rawStrike!, 10) / 1000;
+  const month = MONTH_ABBREV[parseInt(mm!, 10) - 1] || mm;
+  const strikeStr = strike % 1 === 0 ? String(strike) : strike.toFixed(1);
+  return `${underlying} ${side === "C" ? "C" : "P"} $${strikeStr} ${month}'${yy}`;
+}

package/src/utils/price-history.ts

@@ -0,0 +1,39 @@
+import type { PricePoint, TickerFinancials } from "../types/financials";
+
+function getPointTimestamp(point: PricePoint): number {
+  return point.date instanceof Date ? point.date.getTime() : new Date(point.date).getTime();
+}
+
+function comparePricePointsByDate(left: PricePoint, right: PricePoint): number {
+  const leftTime = getPointTimestamp(left);
+  const rightTime = getPointTimestamp(right);
+  const leftValid = Number.isFinite(leftTime);
+  const rightValid = Number.isFinite(rightTime);
+
+  if (leftValid && rightValid) return leftTime - rightTime;
+  if (leftValid) return -1;
+  if (rightValid) return 1;
+  return 0;
+}
+
+export function normalizePriceHistory(points: PricePoint[]): PricePoint[] {
+  if (points.length <= 1) return points;
+
+  let previousTime = Number.NEGATIVE_INFINITY;
+  for (const point of points) {
+    const time = getPointTimestamp(point);
+    if (!Number.isFinite(time) || time < previousTime) {
+      return [...points].sort(comparePricePointsByDate);
+    }
+    previousTime = time;
+  }
+
+  return points;
+}
+
+export function normalizeTickerFinancialsPriceHistory(financials: TickerFinancials): TickerFinancials {
+  const priceHistory = normalizePriceHistory(financials.priceHistory ?? []);
+  return priceHistory === financials.priceHistory
+    ? financials
+    : { ...financials, priceHistory };
+}

package/src/utils/quote-time.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+import { clampQuoteTimestamp, formatQuoteAge, formatQuoteAgeWithSource, getMostRecentQuoteUpdate } from "./quote-time";
+
+describe("quote-time", () => {
+  test("clamps future timestamps to the current render time", () => {
+    expect(clampQuoteTimestamp(12_000, 10_000)).toBe(10_000);
+  });
+
+  test("formats future timestamps as zero age instead of a negative value", () => {
+    expect(formatQuoteAge(12_000, 10_000)).toBe("0s");
+    expect(formatQuoteAgeWithSource({ lastUpdated: 12_000, dataSource: "delayed" }, 10_000)).toBe("◷0s");
+  });
+
+  test("tracks the latest visible quote update", () => {
+    expect(getMostRecentQuoteUpdate([
+      { lastUpdated: 8_000 },
+      null,
+      { lastUpdated: 15_000 },
+      { lastUpdated: 9_000 },
+    ], 10_000)).toBe(10_000);
+  });
+});

package/src/utils/quote-time.ts

@@ -0,0 +1,50 @@
+import type { Quote } from "../types/financials";
+
+export function clampQuoteTimestamp(lastUpdated: number | undefined, now = Date.now()): number | null {
+  if (typeof lastUpdated !== "number" || !Number.isFinite(lastUpdated) || lastUpdated <= 0) {
+    return null;
+  }
+  return Math.min(lastUpdated, now);
+}
+
+export function formatQuoteAge(lastUpdated: number | undefined, now = Date.now()): string {
+  const clamped = clampQuoteTimestamp(lastUpdated, now);
+  if (clamped == null) return "—";
+
+  const ageSeconds = Math.max(0, (now - clamped) / 1000);
+  if (ageSeconds < 60) return `${Math.floor(ageSeconds)}s`;
+  if (ageSeconds < 3600) return `${Math.floor(ageSeconds / 60)}m`;
+  if (ageSeconds < 86400) return `${Math.floor(ageSeconds / 3600)}h`;
+  return `${Math.floor(ageSeconds / 86400)}d`;
+}
+
+export function formatQuoteAgeWithSource(
+  quote: Pick<Quote, "lastUpdated" | "dataSource"> | null | undefined,
+  now = Date.now(),
+): string {
+  if (!quote) return "—";
+
+  const age = formatQuoteAge(quote.lastUpdated, now);
+  if (age === "—") return age;
+
+  const prefix = quote.dataSource === "delayed"
+    ? "◷"
+    : quote.dataSource === "yahoo"
+      ? "◌"
+      : "";
+  return prefix ? `${prefix}${age}` : age;
+}
+
+export function getMostRecentQuoteUpdate(
+  quotes: Iterable<Pick<Quote, "lastUpdated"> | null | undefined>,
+  now = Date.now(),
+): number | null {
+  let latest: number | null = null;
+  for (const quote of quotes) {
+    const timestamp = clampQuoteTimestamp(quote?.lastUpdated, now);
+    if (timestamp != null && (latest == null || timestamp > latest)) {
+      latest = timestamp;
+    }
+  }
+  return latest;
+}

package/src/utils/sec.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import type { TickerRecord } from "../types/ticker";
+import { isUsEquityTicker } from "./sec";
+
+function makeTicker(overrides: Partial<TickerRecord["metadata"]>): TickerRecord {
+  return {
+    metadata: {
+      ticker: "AAPL",
+      exchange: "NASDAQ",
+      currency: "USD",
+      name: "Apple Inc.",
+      portfolios: [],
+      watchlists: [],
+      positions: [],
+      custom: {},
+      tags: [],
+      ...overrides,
+    },
+  };
+}
+
+describe("isUsEquityTicker", () => {
+  test("accepts plain US stocks", () => {
+    expect(isUsEquityTicker(makeTicker({ assetCategory: "STK" }))).toBe(true);
+  });
+
+  test("accepts SMART-routed US stocks with a primary exchange", () => {
+    expect(isUsEquityTicker(makeTicker({
+      exchange: "SMART",
+      assetCategory: "STK",
+      broker_contracts: [{
+        brokerId: "ibkr",
+        symbol: "AAPL",
+        exchange: "SMART",
+        primaryExchange: "NASDAQ",
+        secType: "STK",
+        currency: "USD",
+      }],
+    }))).toBe(true);
+  });
+
+  test("rejects non-US listings", () => {
+    expect(isUsEquityTicker(makeTicker({
+      exchange: "HKEX",
+      currency: "HKD",
+      assetCategory: "STK",
+    }))).toBe(false);
+  });
+
+  test("rejects non-equity instruments", () => {
+    expect(isUsEquityTicker(makeTicker({
+      assetCategory: "OPT",
+    }))).toBe(false);
+  });
+});

package/src/utils/sec.ts

@@ -0,0 +1,45 @@
+import type { TickerRecord } from "../types/ticker";
+
+const US_EQUITY_EXCHANGES = new Set([
+  "AMEX",
+  "ARCA",
+  "BATS",
+  "BYX",
+  "IEX",
+  "NASDAQ",
+  "NMS",
+  "NYSE",
+  "NYSEARCA",
+  "OTC",
+  "PINK",
+]);
+
+function normalize(value?: string): string {
+  return (value ?? "").trim().toUpperCase();
+}
+
+function isUsExchange(value?: string): boolean {
+  return US_EQUITY_EXCHANGES.has(normalize(value));
+}
+
+function isEquityType(value?: string): boolean {
+  const normalized = normalize(value);
+  return normalized.length === 0 || normalized === "STK" || normalized === "EQUITY";
+}
+
+export function isUsEquityTicker(ticker: TickerRecord | null | undefined): boolean {
+  if (!ticker) return false;
+
+  const primaryContract = ticker.metadata.broker_contracts?.[0];
+  const type = primaryContract?.secType ?? ticker.metadata.assetCategory;
+  const currency = normalize(primaryContract?.currency ?? ticker.metadata.currency);
+  const exchangeCandidates = [
+    primaryContract?.primaryExchange,
+    primaryContract?.exchange,
+    ticker.metadata.exchange,
+  ];
+
+  return isEquityType(type)
+    && currency === "USD"
+    && exchangeCandidates.some((exchange) => isUsExchange(exchange));
+}

package/src/utils/ticker-list.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+import { formatTickerListInput, parseTickerListInput } from "./ticker-list";
+
+describe("parseTickerListInput", () => {
+  test("normalizes, de-duplicates, and preserves order", () => {
+    expect(parseTickerListInput(" msft, aapl,\nMSFT, nvda ")).toEqual(["MSFT", "AAPL", "NVDA"]);
+  });
+
+  test("rejects empty ticker lists", () => {
+    expect(() => parseTickerListInput(" , \n ")).toThrow("Enter at least one ticker.");
+  });
+
+  test("rejects lists beyond the maximum size", () => {
+    expect(() => parseTickerListInput("A,B,C,D,E,F,G,H,I,J,K", 10)).toThrow("You can compare up to 10 tickers.");
+  });
+});
+
+describe("formatTickerListInput", () => {
+  test("joins symbols with a stable display format", () => {
+    expect(formatTickerListInput(["AAPL", "MSFT", "NVDA"])).toBe("AAPL, MSFT, NVDA");
+  });
+});

package/src/utils/ticker-list.ts

@@ -0,0 +1,35 @@
+export const MAX_TICKER_LIST_SIZE = 10;
+
+function normalizeTickerToken(value: string): string {
+  return value.trim().toUpperCase();
+}
+
+export function parseTickerListInput(raw: string, maxTickers = MAX_TICKER_LIST_SIZE): string[] {
+  const tokens = raw
+    .split(/[,\n]/)
+    .map(normalizeTickerToken)
+    .filter(Boolean);
+
+  const unique: string[] = [];
+  const seen = new Set<string>();
+
+  for (const token of tokens) {
+    if (seen.has(token)) continue;
+    seen.add(token);
+    unique.push(token);
+  }
+
+  if (unique.length === 0) {
+    throw new Error("Enter at least one ticker.");
+  }
+
+  if (unique.length > maxTickers) {
+    throw new Error(`You can compare up to ${maxTickers} tickers.`);
+  }
+
+  return unique;
+}
+
+export function formatTickerListInput(symbols: string[]): string {
+  return symbols.join(", ");
+}