gloomberb 0.18.4 → 0.19.0

package/src/components/ui/select-button.tsx

@@ -18,6 +18,8 @@ export interface SelectControl {
 export interface SelectButtonOption<T extends string = string> {
   value: T;
   label: string;
+  /** Heading for a contiguous group of choices; never selectable itself. */
+  group?: string;
   /** Trigger wording when the full label is too wide for a pane header. */
   short?: string;
   description?: string;
@@ -130,6 +132,7 @@ export function SelectButton<T extends string = string>({
           choices={options.map((option) => ({
             id: option.value,
             label: option.label,
+            group: option.group,
             description: option.description,
             disabled: option.disabled,
             color: option.color,
@@ -158,7 +161,7 @@ export function SelectButton<T extends string = string>({
           selectRef={(element) => { selectFieldRef.current = element; }}
           onFocus={onFocus}
           value={value}
-          options={options.map((option) => ({ value: option.value, label: option.label, disabled: option.disabled }))}
+          options={options.map((option) => ({ value: option.value, label: option.label, group: option.group, disabled: option.disabled }))}
           disabled={disabled}
           onChange={selectValue}
         />
@@ -180,6 +183,7 @@ export function SelectButton<T extends string = string>({
           options={options.map((option) => ({
             value: option.value,
             label: option.label,
+            group: option.group,
             disabled: option.disabled,
           }))}
           disabled={disabled}

package/src/components/ui/select-field.tsx

@@ -9,6 +9,7 @@ export interface SelectFieldHandle {
 
 interface SelectFieldOption {
   label: string;
+  group?: string;
   value: string;
   description?: string;
   disabled?: boolean;

package/src/components/ui/table-layout.ts

@@ -106,18 +106,21 @@ export function getTableWidth(
  * The columns that fit in `width` cells: whole columns in `dropOrder` (least
  * needed first) give way until the rest fit, rather than the table's right
  * edge cutting a value, so a narrow pane drops a name that repeats its ticker
- * before it cuts a date. Columns not listed stay at every width. A table that
- * scrolls vertically passes its width less the scrollbar's cell.
+ * before it cuts a date. An entry that lists several ids drops them together,
+ * for columns that mean little apart (a bid's venue and an ask's). Columns not
+ * listed stay at every width. A table that scrolls vertically passes its width
+ * less the scrollbar's cell.
  */
 export function dropColumnsToFit<C extends TableWidthColumn & { id: string }>(
   columns: readonly C[],
   width: number,
-  dropOrder: readonly string[],
+  dropOrder: readonly (string | readonly string[])[],
 ): C[] {
   let shown = [...columns];
-  for (const id of dropOrder) {
+  for (const step of dropOrder) {
     if (getTableWidth(shown) <= width) break;
-    shown = shown.filter((column) => column.id !== id);
+    const ids = typeof step === "string" ? [step] : step;
+    shown = shown.filter((column) => !ids.includes(column.id));
   }
   return shown;
 }

package/src/core/app-runtime.ts

@@ -1,5 +1,6 @@
 import { MarketDataCoordinator, getSharedMarketDataCoordinator, setSharedMarketDataCoordinator } from "../market-data/coordinator";
 import { NewsService, type NewsServiceOptions } from "../news/aggregator";
+import { cloudNewsSession } from "../news/cloud-session";
 import { getSharedNewsService, setSharedNewsService } from "../news/hooks";
 import { PluginRegistry } from "../plugins/registry";
 import { releaseSharedRegistry } from "../plugins/registry/shared";
@@ -61,6 +62,7 @@ export function createAppRuntime({
   const newsService = new NewsService({
     connectionHealth: pluginRegistry.connectionHealth,
     pollIntervalMs: () => Math.max(1, config.refreshIntervalMinutes) * 60_000,
+    session: cloudNewsSession,
     ...newsOptions,
   });
   const modules = { pluginRegistry, marketData, newsService };

package/src/core/app-services.ts

@@ -27,8 +27,8 @@ export function createAppServices({ config, plugins, externalPlugins }: AppServi
           provider: {
             fetchNews: async (query) => (await newsService.load(query)).articles,
             fetchNewsPage: async (query) => {
-              const { articles, error, nextCursor } = await newsService.load(query);
-              return { articles, error, nextCursor };
+              const { articles, error, nextCursor, access } = await newsService.load(query);
+              return { articles, error, nextCursor, access };
             },
             getCachedNews: (query) => newsService.getQueryState(query).articles,
           },

package/src/core/state/app/layout.ts

@@ -594,6 +594,7 @@ export function withFocusedPane(
     config: syncedConfig,
     paneState: nextPaneState,
     brokerAccounts: reconcileBrokerAccounts(syncedConfig, state.brokerAccounts),
+    brokerSyncErrors: Object.fromEntries(Object.entries(state.brokerSyncErrors).filter(([id]) => syncedConfig.brokerInstances.some((instance) => instance.id === id))),
     focusedPaneId,
     previousFocusedPaneId: state.focusedPaneId && state.focusedPaneId !== focusedPaneId
       ? state.focusedPaneId
@@ -605,6 +606,7 @@ export function hydrateDesktopSnapshot(state: AppState, snapshot: DesktopSharedS
   return withFocusedPane({
     ...state,
     paneState: snapshot.paneState,
+    brokerSyncErrors: snapshot.brokerSyncErrors ?? {},
     focusedPaneId: snapshot.focusedPaneId,
     statusBarVisible: snapshot.statusBarVisible,
   }, snapshot.config);

package/src/core/state/app/state.ts

@@ -203,6 +203,14 @@ export function appReducer(state: AppState, action: AppAction): AppState {
         },
       };
 
+    case "SET_BROKER_SYNC_ERROR": {
+      if (!state.config.brokerInstances.some((instance) => instance.id === action.instanceId)) return state;
+      const brokerSyncErrors = { ...state.brokerSyncErrors };
+      if (action.error) brokerSyncErrors[action.instanceId] = action.error;
+      else delete brokerSyncErrors[action.instanceId];
+      return { ...state, brokerSyncErrors };
+    }
+
     case "SET_INITIALIZED":
       return { ...state, initialized: true };
 
@@ -371,6 +379,7 @@ export function createInitialState(config: AppConfig, sessionSnapshot: AppSessio
     financials: new Map(),
     exchangeRates: new Map([["USD", 1]]),
     brokerAccounts: {},
+    brokerSyncErrors: {},
     focusedPaneId,
     previousFocusedPaneId: null,
     paneState,

package/src/core/state/app/types.ts

@@ -68,6 +68,8 @@ export interface AppState {
    */
   exchangeRates: Map<string, number>;
   brokerAccounts: Record<string, BrokerAccount[]>;
+  /** A failed position import stays visible until this profile syncs successfully. */
+  brokerSyncErrors: Record<string, string>;
   /**
    * @deprecated Never set. The app has no left or right panel state; read
    * `focusedPaneId` for the focused pane.
@@ -131,6 +133,7 @@ export type AppAction =
   | { type: "RECORD_COMMAND"; id: string; label: string; arg?: string }
   | { type: "SET_REFRESHING"; symbol: string; refreshing: boolean }
   | { type: "SET_BROKER_ACCOUNTS"; instanceId: string; accounts: BrokerAccount[] }
+  | { type: "SET_BROKER_SYNC_ERROR"; instanceId: string; error: string | null }
   | { type: "SET_INITIALIZED" }
   | { type: "TOGGLE_STATUS_BAR" }
   | { type: "SET_THEME"; theme: string }

package/src/data/config/chart-settings.ts

@@ -20,7 +20,7 @@ import {
 import { recordOrNull } from "../../utils/guards";
 
 const CHART_RANGES = new Set<TimeRange>(TIME_RANGES);
-const PRICE_RENDER_MODES = new Set<SeriesStyle>(["area", "line", "candles", "ohlc", "hlc"]);
+const PRICE_RENDER_MODES = new Set<SeriesStyle>(["area", "line", "candles", "hollow", "heikin-ashi", "ohlc", "hlc"]);
 const LEGACY_INDICATOR_IDS = new Set<LegacyChartIndicatorId>([
   "volume",
   "sma20",

package/src/data/json-ticker-repository.ts

@@ -4,6 +4,7 @@ import { hydrateTickerMetadata } from "../tickers/metadata";
 import type { TickerMetadata, TickerRecord } from "../types/ticker";
 import { BROWSER_STORAGE_KEYS, SafeJsonStorage, type StorageLike } from "./json-storage";
 import { isRecord } from "../utils/guards";
+import { runTickerWrite } from "./ticker-writes";
 
 type StoredTickers = Record<string, TickerMetadata>;
 
@@ -39,20 +40,28 @@ export class JsonTickerRepository implements AppTickerRepositoryPort {
     return metadata ? hydrate(metadata) : null;
   }
 
-  async saveTicker(ticker: TickerRecord): Promise<void> {
+  private writeTicker(ticker: TickerRecord): void {
     const symbol = normalizeSymbol(ticker.metadata.ticker);
     this.data.set({ ...this.data.get(), [symbol]: ticker.metadata });
   }
 
-  async createTicker(metadata: TickerMetadata): Promise<TickerRecord> {
+  saveTicker(ticker: TickerRecord): Promise<void> {
+    return runTickerWrite(this, ticker.metadata.ticker, () => this.writeTicker(ticker));
+  }
+
+  createTicker(metadata: TickerMetadata): Promise<TickerRecord> {
     const ticker = { metadata };
-    await this.saveTicker(ticker);
-    return ticker;
+    return runTickerWrite(this, metadata.ticker, () => {
+      this.writeTicker(ticker);
+      return ticker;
+    });
   }
 
-  async deleteTicker(symbol: string): Promise<void> {
-    const tickers = { ...this.data.get() };
-    delete tickers[normalizeSymbol(symbol)];
-    this.data.set(tickers);
+  deleteTicker(symbol: string): Promise<void> {
+    return runTickerWrite(this, symbol, () => {
+      const tickers = { ...this.data.get() };
+      delete tickers[normalizeSymbol(symbol)];
+      this.data.set(tickers);
+    });
   }
 }

package/src/data/saved-copies.ts

@@ -1,27 +1,33 @@
 /**
- * Answers a CLI command gave from a copy saved earlier because refreshing it
- * failed: offline, a refused proxy, a service error. A command answers once,
- * so the line it ends with says "couldn't refresh; saved <time>" instead of
- * reading as live or delayed, but only when what it shows came from such a
- * copy: a saved copy of something else it loaded on the way (a fallback for a
- * pane it does not print) says nothing about the data on screen.
+ * Answers given from a copy saved earlier because refreshing it failed:
+ * offline, a hung or refused proxy, a service error.
+ *
+ * A CLI command answers once, so the line it ends with says "couldn't
+ * refresh; saved copy from <time>" instead of reading as live or delayed, but
+ * only when what it shows came from such a copy: a saved copy of something
+ * else it loaded on the way (a fallback for a pane it does not print) says
+ * nothing about the data on screen. The app says the same of a quote, in the
+ * footer of a pane showing one (`savedCopyAt`), until a refresh replaces it.
  *
  * The copy served is marked, by a symbol property that object spreads carry
  * along and JSON never writes, and the command's output is searched for the
- * marks. Nothing is marked outside `collectSavedCopies`: the app and its panes
- * keep running for hours and say how current their data is in their own
- * footers.
+ * marks. Outside a command only quotes are marked (`quoteServedFromSavedCopy`):
+ * the app keeps running for hours, and its other panes say how current their
+ * data is in their own footers. A quote built from a newer answer must not
+ * inherit a mark through a spread: `withSavedCopyMarkOf` gives it the mark of
+ * what was served instead.
  */
 const SAVED_AT = Symbol("gloomberb.savedCopyAt");
 
 let collecting = 0;
-let marked = 0;
+/** Whether anything was ever marked, so output is not searched for marks that cannot be there. */
+let anyMarked = false;
 
 type Marked = { [SAVED_AT]?: number };
 
 function mark<T>(value: T, savedAt: number): T {
   if (!value || typeof value !== "object" || Array.isArray(value)) return value;
-  marked += 1;
+  anyMarked = true;
   return { ...value, [SAVED_AT]: savedAt };
 }
 
@@ -36,13 +42,48 @@ export function servedFromSavedCopy<T>(value: T, savedAt: number): T {
   return (Array.isArray(value) ? value.map((item) => mark(item, savedAt)) : mark(value, savedAt)) as T;
 }
 
+/** A quote answered from a copy saved at `savedAt` (ms) after its refresh failed: marked, in a command and in the app. */
+export function quoteServedFromSavedCopy<T extends object>(quote: T, savedAt: number): T {
+  return Number.isFinite(savedAt) ? mark(quote, savedAt) : quote;
+}
+
 /**
  * The saved-copy mark of `value`, to spread into what is drawn from it (a
  * report row built from a quote's fields), or nothing when it has none.
  */
 export function savedCopyMark(value: unknown): object {
+  const savedAt = savedCopyAt(value);
+  return savedAt != null ? { [SAVED_AT]: savedAt } : {};
+}
+
+/** When `value` itself was saved, if it is a saved copy served after a failed refresh; null otherwise. */
+export function savedCopyAt(value: unknown): number | null {
   const savedAt = value && typeof value === "object" ? (value as Marked)[SAVED_AT] : undefined;
-  return typeof savedAt === "number" ? { [SAVED_AT]: savedAt } : {};
+  return typeof savedAt === "number" ? savedAt : null;
+}
+
+/** The oldest saved copy among `values` (a pane's quotes), by when it was saved; null when none is one. */
+export function oldestSavedCopyAt(values: Iterable<unknown>): number | null {
+  let oldest: number | null = null;
+  for (const value of values) {
+    const savedAt = savedCopyAt(value);
+    if (savedAt != null) oldest = Math.min(oldest ?? savedAt, savedAt);
+  }
+  return oldest;
+}
+
+/**
+ * `value` carrying the saved-copy mark of `served` and no other: what is
+ * built from an answer (resolved, merged onto an older quote) is a saved copy
+ * exactly when that answer was.
+ */
+export function withSavedCopyMarkOf<T extends object>(value: T, served: unknown): T {
+  const savedAt = savedCopyAt(served);
+  const own = savedCopyAt(value);
+  if (own === savedAt) return value;
+  if (savedAt != null) return mark(value, savedAt);
+  const { [SAVED_AT]: _dropped, ...rest } = value as T & Marked;
+  return rest as T;
 }
 
 /** How far into a command's output the marks are looked for, so a large report is not walked whole. */
@@ -55,7 +96,7 @@ const MAX_NODES = 50_000;
  * came from one. The oldest, since that is how old what is shown can be.
  */
 export function savedCopyShownAt(shown: unknown): number | null {
-  if (collecting === 0 || marked === 0) return null;
+  if (collecting === 0 || !anyMarked) return null;
   let oldest: number | null = null;
   let budget = MAX_NODES;
   const seen = new Set<object>();
@@ -71,14 +112,12 @@ export function savedCopyShownAt(shown: unknown): number | null {
   return oldest;
 }
 
-/** Runs one command, marking the saved copies it answers from. */
+/** Runs one command, whose output `savedCopyShownAt` then searches for saved copies. */
 export async function collectSavedCopies<T>(run: () => Promise<T>): Promise<T> {
-  if (collecting === 0) marked = 0;
   collecting += 1;
   try {
     return await run();
   } finally {
     collecting -= 1;
-    if (collecting === 0) marked = 0;
   }
 }

package/src/data/ticker-repository.ts

@@ -2,6 +2,7 @@ import { logFailure } from "../utils/log-failure";
 import type { TickerRecord, TickerMetadata } from "../types/ticker";
 import type { TickerStore } from "./ticker-store";
 import { hydrateTickerMetadata } from "../tickers/metadata";
+import { runTickerWrite } from "./ticker-writes";
 
 function parseTickerMetadata(json: string): TickerMetadata {
   return hydrateTickerMetadata(JSON.parse(json) as Record<string, unknown>);
@@ -32,22 +33,28 @@ export class TickerRepository {
     }
   }
 
-  async saveTicker(ticker: TickerRecord): Promise<void> {
-    this.tickers.save(ticker.metadata.ticker, ticker.metadata);
+  saveTicker(ticker: TickerRecord): Promise<void> {
+    return runTickerWrite(this, ticker.metadata.ticker, () => {
+      this.tickers.save(ticker.metadata.ticker, ticker.metadata);
+    });
   }
 
   /** Saves several tickers in one write. */
-  async saveTickers(tickers: readonly TickerRecord[]): Promise<void> {
-    this.tickers.saveMany(tickers.map((ticker) => ({ symbol: ticker.metadata.ticker, metadata: ticker.metadata })));
+  saveTickers(tickers: readonly TickerRecord[]): Promise<void> {
+    return runTickerWrite(this, tickers.map((ticker) => ticker.metadata.ticker), () => {
+      this.tickers.saveMany(tickers.map((ticker) => ({ symbol: ticker.metadata.ticker, metadata: ticker.metadata })));
+    });
   }
 
-  async createTicker(metadata: TickerMetadata): Promise<TickerRecord> {
+  createTicker(metadata: TickerMetadata): Promise<TickerRecord> {
     const ticker: TickerRecord = { metadata };
-    await this.saveTicker(ticker);
-    return ticker;
+    return runTickerWrite(this, metadata.ticker, () => {
+      this.tickers.save(metadata.ticker, metadata);
+      return ticker;
+    });
   }
 
-  async deleteTicker(symbol: string): Promise<void> {
-    this.tickers.delete(symbol);
+  deleteTicker(symbol: string): Promise<void> {
+    return runTickerWrite(this, symbol, () => this.tickers.delete(symbol));
   }
 }

package/src/data/ticker-writes.ts

@@ -0,0 +1,81 @@
+interface TickerWrites {
+  revisions: Map<string, number>;
+  tails: Map<string, Promise<unknown>>;
+  pending: Set<Promise<unknown>>;
+}
+
+const repositories = new WeakMap<object, TickerWrites>();
+
+function writesFor(repository: object): TickerWrites {
+  let writes = repositories.get(repository);
+  if (!writes) {
+    writes = { revisions: new Map(), tails: new Map(), pending: new Set() };
+    repositories.set(repository, writes);
+  }
+  return writes;
+}
+
+function tickerKey(symbol: string): string {
+  return symbol.trim().toUpperCase();
+}
+
+/** Reserve writes when requested, including ones waiting for an earlier acknowledgement. */
+export function runTickerWrite<Result>(
+  repository: object,
+  symbols: string | readonly string[],
+  write: () => Result | PromiseLike<Result>,
+): Promise<Result> {
+  const writes = writesFor(repository);
+  const keys = [...new Set((typeof symbols === "string" ? [symbols] : symbols).map(tickerKey))];
+  const previous = [...new Set(keys.flatMap((key) => {
+    const tail = writes.tails.get(key);
+    return tail ? [tail] : [];
+  }))];
+  let resolve!: (value: Result | PromiseLike<Result>) => void;
+  let reject!: (error: unknown) => void;
+  const result = new Promise<Result>((accept, fail) => {
+    resolve = accept;
+    reject = fail;
+  });
+  for (const key of keys) {
+    writes.revisions.set(key, (writes.revisions.get(key) ?? 0) + 1);
+    writes.tails.set(key, result);
+  }
+  writes.pending.add(result);
+  const finished = () => {
+    writes.pending.delete(result);
+    for (const key of keys) {
+      if (writes.tails.get(key) === result) writes.tails.delete(key);
+    }
+  };
+  void result.then(finished, finished);
+  const start = () => {
+    try {
+      resolve(write());
+    } catch (error) {
+      reject(error);
+    }
+  };
+  if (previous.length) void Promise.allSettled(previous).then(start);
+  else start();
+  return result;
+}
+
+/** Changes immediately when a save or deletion is requested, before its acknowledgement. */
+export function tickerWriteRevision(repository: object, symbol: string): number {
+  return repositories.get(repository)?.revisions.get(tickerKey(symbol)) ?? 0;
+}
+
+/** Whether a write arrived after a caller last waited for acknowledgements. */
+export function hasPendingTickerWrites(repository: object): boolean {
+  return (repositories.get(repository)?.pending.size ?? 0) > 0;
+}
+
+/** Let save-await callers publish their edits before cleanup reads the current rows. */
+export async function settleTickerWrites(repository: object): Promise<void> {
+  const writes = writesFor(repository);
+  do {
+    // Each writer handles its own failure; cleanup still needs the last published row.
+    await Promise.allSettled([...writes.pending]);
+  } while (writes.pending.size);
+}

package/src/data/ttl-cache.ts

@@ -0,0 +1,165 @@
+/**
+ * A keyed in-memory cache that serves a loaded value for a while and shares a
+ * load that is still out. It is what a plugin reaches for instead of keeping
+ * its own `Map<key, { at, value }>` with a TTL constant and `Date.now() - at`
+ * checks, each copy with its own rule for a concurrent call, a forced reload
+ * and a failed load.
+ *
+ * It holds nothing across a restart, and `load` never answers with an expired
+ * value. A pane whose data must outlive a restart, or fall back to the saved
+ * copy when a refresh fails, wants `createPluginCache` (src/data/plugin-cache.ts).
+ *
+ * The rules, for every key:
+ * - A fresh value is served as it is; a load that is still out is shared, so
+ *   two callers never start two requests for one key. A load is shared for
+ *   no longer than `ttlMs` (a number), so one that hangs cannot hold the key.
+ * - `force` skips a fresh value and starts a load, except that it joins one
+ *   that is already out when that load began after the value it would
+ *   replace: panes that refresh together make one request, not one each.
+ * - The last good value stays until a load brings a newer one. A forced
+ *   load that fails, or brings a value `keep` refuses, leaves it in place,
+ *   and `peek(key, { stale: true })` reads it past its TTL while a reload is
+ *   out, for a view that keeps drawing the last copy.
+ * - A load that rejects reaches every caller waiting on it. By default
+ *   nothing is kept, so the next call asks again; `rejectionMs` keeps the
+ *   rejection that long, for a load a poll would otherwise repeat each tick.
+ * - A load runs as soon as `load` is called, not on a later tick.
+ */
+export interface TtlCacheOptions<V> {
+  /** How long a loaded value is served, from when it arrives; a function sets it per value. */
+  ttlMs: number | ((value: V) => number);
+  /**
+   * Whether a loaded value is kept. One that is not still answers the callers
+   * waiting on it, and the next call loads again. Default: every value.
+   */
+  keep?: (value: V) => boolean;
+  /** How long a rejected load is kept and served again. Default 0: it is dropped. */
+  rejectionMs?: number;
+  /** The oldest keys go first past this many. Default: unbounded. */
+  maxEntries?: number;
+  /** The clock, for tests. */
+  now?: () => number;
+}
+
+export interface TtlCache<V> {
+  /** The key's fresh value or the load already out for it; otherwise starts `load`. */
+  load(key: string, load: () => V | PromiseLike<V>, options?: { force?: boolean }): Promise<V>;
+  /**
+   * The key's fresh value, `undefined` when it has none. `stale` also reads
+   * the last good value past its TTL, for a view that keeps drawing it until
+   * the next load lands.
+   */
+  peek(key: string, options?: { stale?: boolean }): V | undefined;
+  /** Whether the key's last load was rejected and `rejectionMs` still keeps that rejection. */
+  failed(key: string): boolean;
+  /** Keeps a value that arrived by another road, for the TTL. */
+  set(key: string, value: V): void;
+  /**
+   * Forgets the key. With `only`, a promise `load` returned, forgets just the
+   * load or kept rejection it stands for, and only while it is still the
+   * key's: a caller that gives up on a load cannot drop a newer one.
+   */
+  delete(key: string, only?: Promise<V>): void;
+  clear(): void;
+}
+
+interface Slot<V> {
+  /** The last good value: fresh until `expiresAt`, readable as stale after. */
+  held?: { value: V; arrivedAt: number; expiresAt: number };
+  /** The load that is out. */
+  loading?: { promise: Promise<V>; startedAt: number };
+  /** A rejected load kept for `rejectionMs`. */
+  failed?: { promise: Promise<V>; expiresAt: number };
+}
+
+export function createTtlCache<V>(options: TtlCacheOptions<V>): TtlCache<V> {
+  const { keep = () => true, rejectionMs = 0, maxEntries = Infinity, now: clock = () => Date.now() } = options;
+  const ttlFor = (value: V) => typeof options.ttlMs === "function" ? options.ttlMs(value) : options.ttlMs;
+  const shareMs = typeof options.ttlMs === "number" ? options.ttlMs : Infinity;
+  const slots = new Map<string, Slot<V>>();
+
+  const store = (key: string, slot: Slot<V>) => {
+    slots.delete(key);
+    slots.set(key, slot);
+    while (slots.size > maxEntries) slots.delete(slots.keys().next().value!);
+  };
+  /** A slot with nothing in it is not kept. */
+  const tidy = (key: string, slot: Slot<V>) => {
+    if (!slot.held && !slot.loading && !slot.failed && slots.get(key) === slot) slots.delete(key);
+  };
+  const hold = (slot: Slot<V>, value: V) => {
+    const arrivedAt = clock();
+    slot.held = { value, arrivedAt, expiresAt: arrivedAt + ttlFor(value) };
+    slot.failed = undefined;
+  };
+
+  return {
+    load(key, load, { force = false } = {}) {
+      const at = clock();
+      const slot = slots.get(key) ?? {};
+      const { held, loading, failed } = slot;
+      if (!force) {
+        if (held && held.expiresAt > at) return Promise.resolve(held.value);
+        if (failed && failed.expiresAt > at) return failed.promise;
+      }
+      if (loading && at - loading.startedAt < shareMs && (!force || !held || loading.startedAt >= held.arrivedAt)) return loading.promise;
+
+      const run: NonNullable<Slot<V>["loading"]> = { promise: undefined as unknown as Promise<V>, startedAt: at };
+      const current = () => slots.get(key)?.loading === run;
+      run.promise = new Promise<V>((resolve) => resolve(load())).then((value) => {
+        if (current()) {
+          slot.loading = undefined;
+          try {
+            // A `keep` or TTL function that throws rejects for the callers, like the load.
+            if (keep(value)) hold(slot, value);
+          } finally {
+            tidy(key, slot);
+          }
+        }
+        return value;
+      }, (error: unknown) => {
+        if (current()) {
+          slot.loading = undefined;
+          const fresh = slot.held && slot.held.expiresAt > clock();
+          if (rejectionMs > 0 && !fresh) slot.failed = { promise: run.promise, expiresAt: clock() + rejectionMs };
+          tidy(key, slot);
+        }
+        throw error;
+      });
+      // A caller that drops the promise must not raise an unhandled rejection.
+      run.promise.then(undefined, () => { /* Intentional ignore: every caller holds this promise and sees the rejection. */ });
+      slot.loading = run;
+      slot.failed = undefined;
+      store(key, slot);
+      return run.promise;
+    },
+    peek(key, { stale = false } = {}) {
+      const held = slots.get(key)?.held;
+      return held && (stale || held.expiresAt > clock()) ? held.value : undefined;
+    },
+    failed(key) {
+      const failed = slots.get(key)?.failed;
+      return !!failed && failed.expiresAt > clock();
+    },
+    set(key, value) {
+      if (!keep(value)) return;
+      const slot = slots.get(key) ?? {};
+      hold(slot, value);
+      store(key, slot);
+    },
+    delete(key, only) {
+      const slot = slots.get(key);
+      if (!slot) return;
+      if (!only) {
+        slots.delete(key);
+        return;
+      }
+      if (slot.loading?.promise === only) slot.loading = undefined;
+      if (slot.failed?.promise === only) slot.failed = undefined;
+      tidy(key, slot);
+    },
+    clear() {
+      slots.clear();
+    },
+  };
+}