dsh-plugin-show-me-data 0.1.0

package/src/app/refresh.js

@@ -0,0 +1,251 @@
+/**
+ * Refresh orchestration: cache, TTL, in-flight de-duplication, retry and
+ * graceful degradation (docs/02 §4.2, docs/07 T6.1).
+ *
+ * This is the only place that decides *when* a source is called. Adapters know
+ * how to fetch; this module knows whether it is worth fetching, what to do when
+ * it fails, and what to tell the UI about freshness.
+ *
+ * @module app/refresh
+ */
+import { SourceError, toSourceErrorPayload } from '../core/types.js'
+import { daysBetween } from '../core/time/range.js'
+
+/** Per-source fetch budget. Keeps one blocked upstream from eating the panel's
+ * whole refresh budget (the browser half abandons a request at 8s). */
+export const SOURCE_TIMEOUT_MS = 6000
+
+/** Cache TTL in minutes, by indicator frequency (docs/02 §4.2). */
+export const TTL_MINUTES = { daily: 15, weekly: 180, monthly: 360, quarterly: 1440, annual: 1440 }
+
+/** Staleness threshold in days, by frequency (docs/05 §5). */
+export const STALE_DAYS = { daily: 2, weekly: 10, monthly: 40, quarterly: 100, annual: 400 }
+
+/**
+ * Canonicalize an adapter params object into a stable cache-key fragment.
+ *
+ * Every parameter is included, sorted by key: one series can serve several
+ * indicators that differ only by a parameter (the Treasury yield curve serves
+ * every tenor from one CSV name), and a key that ignored the parameter would
+ * hand the first tenor's values to all of them.
+ *
+ * @param {object|undefined} params - adapter params.
+ * @returns {string} canonical fragment.
+ */
+export function paramsKey(params) {
+  if (params === null || params === undefined) return ''
+  if (typeof params !== 'object') return String(params)
+  const parts = []
+  for (const key of Object.keys(params).sort()) {
+    const value = params[key]
+    if (value === undefined) continue
+    parts.push(`${key}=${typeof value === 'object' ? paramsKey(value) : String(value)}`)
+  }
+  return parts.join(',')
+}
+
+/**
+ * Cache key for one series request.
+ *
+ * @param {{ adapterId: string, seriesRef: string, params?: object, range?: object }} request - request identity.
+ * @returns {string} cache key.
+ */
+export function cacheKey({ adapterId, seriesRef, params, range }) {
+  return `${adapterId}|${seriesRef}|${paramsKey(params)}|${range?.preset ?? 'CUSTOM'}|${range?.from ?? ''}|${range?.to ?? ''}`
+}
+
+/**
+ * Whether a cached entry is still fresh.
+ *
+ * @param {{ storedAt: string, ttlMs: number }} entry - cache entry.
+ * @param {Date} now - current time.
+ * @returns {boolean} freshness.
+ */
+export function isFresh(entry, now) {
+  const stored = new Date(entry.storedAt).getTime()
+  return now.getTime() - stored < entry.ttlMs
+}
+
+/**
+ * Create the refresh service.
+ *
+ * @param {object} deps - dependencies.
+ * @param {import('../ports/snapshot-repo.js').SnapshotRepository} deps.snapshots - snapshot cache.
+ * @param {import('../ports/clock.js').Clock} deps.clock - clock.
+ * @param {(adapterId: string, req: object, deps: object) => Promise<object>} deps.fetchViaAdapter - adapter dispatcher.
+ * @param {(msg: string, meta?: object) => void} [deps.log] - logger.
+ * @param {{ sleep?: (ms: number) => Promise<void>, retryDelayMs?: number, maxAttempts?: number, ttlMinutes?: object, staleDays?: object }} [deps.options] - tuning.
+ * @returns {object} refresh service.
+ */
+export function createRefreshService({
+  snapshots,
+  clock,
+  fetchViaAdapter,
+  log = () => {},
+  options = {},
+}) {
+  const ttlMinutes = options.ttlMinutes ?? TTL_MINUTES
+  const staleDays = options.staleDays ?? STALE_DAYS
+  const maxAttempts = options.maxAttempts ?? 2
+  const retryDelayMs = options.retryDelayMs ?? 500
+  // Sleeping is injected: `core/` and `app/` hold no timers (test/core/layering.test.js),
+  // and the host half supplies a real delay via its timer service.
+  const sleep = options.sleep ?? (async () => {})
+  const sourceTimeoutMs = options.sourceTimeoutMs ?? SOURCE_TIMEOUT_MS
+  // An adapter may declare a longer budget than the default (docs/04 §8).
+  /** Adapter-specific budget lookup: '(adapterId) => ms|undefined'. */
+  const timeoutFor = options.timeoutFor
+  /** @type {Map<string, Promise<any>>} */
+  const inFlight = new Map()
+
+  /**
+   * Attach freshness metadata to a series result.
+   *
+   * @param {object} series - raw series.
+   * @param {string} status - fresh | stale | error | missing.
+   * @param {object} [extra] - extra fields.
+   * @returns {object} annotated series.
+   */
+  function annotate(series, status, extra = {}) {
+    const latestAt = series?.points?.length ? series.points[series.points.length - 1].t : undefined
+    const ageDays = latestAt === undefined ? undefined : daysBetween(latestAt, clock.today())
+    return { ...series, status, latestAt, ageDays, ...extra }
+  }
+
+  /**
+   * Decide the freshness status for a successful fetch.
+   *
+   * @param {object} series - raw series.
+   * @param {string} freq - indicator frequency.
+   * @returns {'fresh'|'stale'|'missing'} status.
+   */
+  function statusFor(series, freq) {
+    if (!series?.points || series.points.length === 0) return 'missing'
+    const latestAt = series.points[series.points.length - 1].t
+    const threshold = staleDays[freq] ?? 40
+    return daysBetween(latestAt, clock.today()) > threshold ? 'stale' : 'fresh'
+  }
+
+  /**
+   * Fetch one indicator, using the cache when allowed.
+   *
+   * @param {object} req - request.
+   * @param {string} req.adapterId - adapter id.
+   * @param {string} req.seriesRef - series reference.
+   * @param {object} [req.params] - adapter params.
+   * @param {{ preset: string, from: string, to: string }} req.range - date range.
+   * @param {string} [req.freq] - indicator frequency (TTL/staleness).
+   * @param {AbortSignal} [req.signal] - cancellation.
+   * @param {{ force?: boolean, fetch?: Function, clock?: object }} req.runtime - the adapter runtime ('{ fetch, clock }'), plus an optional 'force' override. This object *is* the deps bag the adapters receive.
+   * @returns {Promise<object>} annotated series: '{ adapterId, seriesRef, points, stats?, sourceRef, status, cached, lastSuccessAt, error? }'.
+   */
+  async function refresh(req) {
+    const { adapterId, seriesRef, params, range, freq = 'monthly', runtime } = req
+    const key = cacheKey({ adapterId, seriesRef, params, range })
+    const ttlMs = (ttlMinutes[freq] ?? 360) * 60_000
+
+    if (runtime.force !== true) {
+      const cached = await snapshots.read(key)
+      if (cached !== undefined && isFresh(cached, clock.now())) {
+        return annotate(cached.payload, statusFor(cached.payload, freq), {
+          cached: true,
+          lastSuccessAt: cached.storedAt,
+        })
+      }
+    }
+
+    const existing = inFlight.get(key)
+    if (existing !== undefined) {
+      // Concurrent callers share one upstream call (docs/08 §2 defect 13).
+      const shared = await existing
+      return { ...shared, cached: true, deduped: true }
+    }
+
+    // Register the in-flight promise synchronously: a second caller arriving in
+    // the same tick must find it, not start its own request.
+    const operation = (async () => {
+      let lastError
+      for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+          // `runtime` is the adapter deps bag itself (`{ fetch, clock }`); the
+          // optional `force` flag rides along and is ignored by adapters.
+          // A per-source timeout means one slow or blocked upstream cannot hold
+          // up the whole overview (docs/04 §8: 15s per request, 6s per source
+          // here so a failing source degrades while the others render).
+          const sourceDeps = runtime?.signal === undefined && typeof AbortSignal?.timeout === 'function'
+            ? { ...runtime, signal: AbortSignal.timeout(timeoutFor?.(adapterId) ?? sourceTimeoutMs) }
+            : runtime
+          const series = await fetchViaAdapter(adapterId, { seriesRef, params, range, preset: range?.preset }, sourceDeps)
+          await snapshots.write(key, series, { ttlMs, at: clock.now().toISOString() })
+          return annotate(series, statusFor(series, freq), { cached: false, lastSuccessAt: clock.now().toISOString() })
+        } catch (error) {
+          lastError = error
+          const payload = toSourceErrorPayload(error, adapterId, seriesRef)
+          const retryable = error instanceof SourceError ? error.retryable : false
+          if (!retryable || attempt === maxAttempts) break
+          log(`retrying ${adapterId}/${seriesRef} after ${payload.kind}`, payload)
+          await sleep(retryDelayMs * attempt)
+        }
+      }
+
+      const payload = toSourceErrorPayload(lastError, adapterId, seriesRef)
+      const previous = await snapshots.read(key)
+      if (previous !== undefined) {
+        // Degrade to the last good snapshot rather than dropping the card.
+        return annotate(previous.payload, 'stale', {
+          cached: true,
+          lastSuccessAt: previous.storedAt,
+          error: payload,
+          indicatorId: req.indicatorId,
+        })
+      }
+      return {
+        adapterId,
+        seriesRef,
+        indicatorId: req.indicatorId,
+        points: [],
+        meta: { name: seriesRef },
+        fetchedAt: clock.now().toISOString(),
+        sourceRef: undefined,
+        status: 'error',
+        cached: false,
+        lastSuccessAt: undefined,
+        error: payload,
+      }
+    })()
+    inFlight.set(key, operation)
+    operation.finally(() => {
+      if (inFlight.get(key) === operation) inFlight.delete(key)
+    }).catch(() => {})
+
+    return operation
+  }
+
+  /**
+   * Refresh many requests without letting one failure affect the others
+   * ('Promise.allSettled' semantics, docs/04 §8).
+   *
+   * @param {Array<object>} requests - refresh requests.
+   * @returns {Promise<object[]>} one result per request, in input order.
+   */
+  async function refreshAll(requests) {
+    const settled = await Promise.allSettled(requests.map((request) => refresh(request)))
+    return settled.map((outcome, index) => {
+      if (outcome.status === 'fulfilled') return outcome.value
+      const request = requests[index]
+      return {
+        adapterId: request.adapterId,
+        seriesRef: request.seriesRef,
+        indicatorId: request.indicatorId,
+        points: [],
+        meta: { name: request.seriesRef },
+        fetchedAt: clock.now().toISOString(),
+        status: 'error',
+        cached: false,
+        error: { kind: 'parse', adapterId: request.adapterId, seriesRef: request.seriesRef, detail: String(outcome.reason?.message ?? outcome.reason), retryable: false },
+      }
+    })
+  }
+
+  return { refresh, refreshAll, cacheKey, isFresh, statusFor, inFlightSize: () => inFlight.size }
+}

package/src/app/series-view.js

@@ -0,0 +1,195 @@
+/**
+ * Single-indicator detail view (docs/07 T6.3).
+ *
+ * @module app/series-view
+ */
+import { applyTransform, stats as computeStats } from '../core/stats/series.js'
+import { applyDerive, innerJoin } from '../core/stats/derive.js'
+import { filterRange, resolveRange } from '../core/time/range.js'
+
+/** Error codes the detail view can return. */
+export const VIEW_ERRORS = {
+  unknownIndicator: 'unknown-indicator',
+  insufficientOverlap: 'insufficient-overlap',
+  noData: 'no-data',
+}
+
+/**
+ * Create the series-view use case.
+ *
+ * @param {object} deps - dependencies.
+ * @param {Record<string, object>} deps.catalogById - id → definition.
+ * @param {object} deps.refresh - refresh service.
+ * @param {import('../ports/clock.js').Clock} deps.clock - clock.
+ * @param {object} deps.runtime - runtime deps for adapters.
+ * @returns {object} series-view use case.
+ */
+export function createSeriesViewUseCase({ catalogById, refresh, clock, runtime }) {
+  /**
+   * Fetch one indicator and shape it into a 'SeriesView'.
+   *
+   * @param {object} request - request.
+   * @param {string} request.indicatorId - indicator id.
+   * @param {string} [request.range] - range preset.
+   * @param {object} [request.custom] - custom bounds.
+   * @param {string} [request.transform] - transform override.
+   * @param {string} [request.compareWith] - second indicator id.
+   * @param {{ fetch: Function, clock: object }} [request.runtime] - runtime override.
+   * @returns {Promise<object>} a 'SeriesView', or '{ error: { code, detail } }'.
+   */
+  async function seriesView(request = {}) {
+    const indicator = catalogById[request.indicatorId]
+    if (indicator === undefined) {
+      return { error: { code: VIEW_ERRORS.unknownIndicator, detail: `unknown indicator ${request.indicatorId}` } }
+    }
+    const range = resolveRange(request.range ?? '1Y', clock.today(), request.custom)
+    const runtimeDeps = request.runtime ?? runtime
+    const display = { ...indicator.display, ...(request.transform === undefined ? {} : { transform: request.transform }) }
+
+    /**
+     * Fetch one indicator's raw series through the refresh service.
+     *
+     * @param {object} def - indicator definition.
+     * @returns {Promise<object>} refresh result.
+     */
+    async function fetchOne(def) {
+      if (def.derive !== undefined) {
+        const operandResults = await Promise.all(
+          def.derive.operands.map((operand) => {
+            const operandDef = catalogById[operand]
+            return refresh.refresh({
+              adapterId: operandDef.source.adapter,
+              seriesRef: operandDef.source.seriesRef,
+              params: operandDef.source.params,
+              range,
+              freq: operandDef.freq,
+              runtime: runtimeDeps,
+            })
+          }),
+        )
+        const seriesById = {}
+        operandResults.forEach((result, index) => {
+          if (result.points?.length) seriesById[def.derive.operands[index]] = result.points
+        })
+        const derived = applyDerive(def.derive, seriesById)
+        // Same provenance rule as the overview: a derived series points at its
+        // first operand, labelled so nobody mistakes it for an upstream series.
+        const operandRef = operandResults.find((result) => result.sourceRef)?.sourceRef
+        const sourceRef = operandRef === undefined
+          ? undefined
+          : { ...operandRef, seriesRef: def.derive.operands.join('+'), label: `${operandRef.label}（现算）` }
+        return {
+          adapterId: 'derived',
+          seriesRef: def.derive.operands.join('+'),
+          points: derived.points,
+          meta: { name: def.label.zh, freq: def.freq },
+          fetchedAt: clock.now().toISOString(),
+          sourceRef,
+          status: derived.points.length > 0 ? 'fresh' : 'missing',
+          reason: derived.reason,
+        }
+      }
+      return refresh.refresh({
+        adapterId: def.source.adapter,
+        seriesRef: def.source.seriesRef,
+        // A caller may override source params (the chart's day/week/month bar
+        // size). The override is part of the cache key, so a weekly request never
+        // reuses the daily response.
+        params: request.params === undefined ? def.source.params : { ...def.source.params, ...request.params },
+        range,
+        freq: def.freq,
+        runtime: runtimeDeps,
+      })
+    }
+
+    const primary = await fetchOne(indicator)
+    if (primary.status === 'error') {
+      return {
+        indicatorId: indicator.id,
+        label: indicator.label,
+        unit: indicator.unit,
+        range,
+        points: [],
+        stats: undefined,
+        sourceRef: primary.sourceRef,
+        status: 'error',
+        errorKind: primary.error?.kind,
+        errorDetail: primary.error?.detail,
+      }
+    }
+
+    const transformedAll = applyTransform(primary.points ?? [], display)
+    const points = filterRange(transformedAll, range)
+    // Descriptive statistics describe the whole fetched series (a YoY reading
+    // needs twelve prior points even when the chart shows three months), but the
+    // reported *count* must agree with the points actually returned. They used to
+    // disagree — `/series` answered with 10 points while its own `stats.count`
+    // said 13 — and a model reading both found the contradiction before a human did.
+    const stats = computeStats(transformedAll, { decimals: display.decimals, freq: indicator.freq })
+    if (stats !== undefined) stats.count = points.length
+
+    const view = {
+      indicatorId: indicator.id,
+      label: indicator.label,
+      unit: indicator.unit,
+      unitLabel: unitLabel(indicator, display),
+      freq: indicator.freq,
+      seasonal: indicator.seasonal,
+      display,
+      range,
+      points,
+      stats,
+      sourceRef: primary.sourceRef,
+      // Whether a day/week/month switch would change anything for this source.
+      // The panel shows the control only when it is true.
+      barSizes: request.barSizes === true,
+      status: points.length === 0 ? 'missing' : primary.status,
+      lastSuccessAt: primary.lastSuccessAt,
+    }
+
+    if (request.compareWith !== undefined) {
+      const other = catalogById[request.compareWith]
+      if (other === undefined) {
+        return { error: { code: VIEW_ERRORS.unknownIndicator, detail: `unknown comparison indicator ${request.compareWith}` } }
+      }
+      const secondary = await fetchOne(other)
+      const otherPoints = filterRange(applyTransform(secondary.points ?? [], other.display), range)
+      const joined = innerJoin(points, otherPoints)
+      if (joined.length < 3) {
+        return {
+          error: {
+            code: VIEW_ERRORS.insufficientOverlap,
+            detail: `${indicator.id} and ${other.id} share only ${joined.length} dates in this range`,
+          },
+          view,
+        }
+      }
+      view.compare = {
+        indicatorId: other.id,
+        label: other.label,
+        unit: other.unit,
+        points: otherPoints,
+        join: joined,
+        stats: computeStats(applyTransform(secondary.points ?? [], other.display), { decimals: other.display?.decimals, freq: other.freq }),
+      }
+    }
+
+    return view
+  }
+
+  return { seriesView }
+}
+
+/**
+ * The unit label including any transform annotation (e.g. '% (年化)').
+ *
+ * @param {object} indicator - indicator definition.
+ * @param {object} display - effective display spec.
+ * @returns {string} unit label.
+ */
+export function unitLabel(indicator, display) {
+  const parts = [indicator.unit]
+  if (display.transform === 'annualize') parts.push('年化')
+  if (display.movingAvg !== undefined) parts.push(`${display.movingAvg}期均值`)
+  return parts.join(' ')
+}

package/src/app/watchlist.js

@@ -0,0 +1,102 @@
+/**
+ * The watchlist / custom-indicator use case (docs/07 T6.4).
+ *
+ * The repository is injected, so the in-memory and file-backed implementations
+ * share one behaviour: 'add' is idempotent, 'remove' reports 'notFound' instead
+ * of throwing, and 'update' patches only the fields it was given.
+ *
+ * @module app/watchlist
+ */
+import { validateIndicatorDef } from '../core/types.js'
+
+/**
+ * Create the watchlist use case.
+ *
+ * @param {object} deps - dependencies.
+ * @param {import('../ports/snapshot-repo.js').WatchlistRepository} deps.repository - persistence.
+ * @param {import('../ports/clock.js').Clock} deps.clock - clock.
+ * @param {Record<string, object>} [deps.catalogById] - seed catalog, for id collision reporting.
+ * @returns {object} watchlist use case.
+ */
+export function createWatchlistUseCase({ repository, clock, catalogById = {} }) {
+  /**
+   * List the stored items, ordered by their 'order' field then insertion.
+   *
+   * @returns {Promise<object[]>} items.
+   */
+  async function list() {
+    const items = await repository.list()
+    return items
+      .map((item, index) => ({ ...item, _index: index }))
+      .sort((a, b) => (a.order ?? a._index) - (b.order ?? b._index))
+      .map(({ _index, ...item }) => item)
+  }
+
+  /**
+   * Add an indicator (idempotent).
+   *
+   * @param {object} item - '{ indicatorId, ... }'.
+   * @param {{ createdBy?: 'user'|'ai'|'catalog' }} [options] - provenance.
+   * @returns {Promise<{ item: object, created: boolean, conflict?: boolean }>} result.
+   */
+  async function add(item, { createdBy = 'user' } = {}) {
+    const indicatorId = item?.indicatorId
+    if (typeof indicatorId !== 'string' || indicatorId === '') {
+      return { item: undefined, created: false, error: { code: 'invalid-item', detail: 'indicatorId is required' } }
+    }
+    if (item.definition !== undefined) {
+      const validation = validateIndicatorDef(item.definition)
+      if (!validation.ok) {
+        return { item: undefined, created: false, error: { code: 'invalid-definition', detail: validation.errors.join('; ') } }
+      }
+    }
+    const stored = { ...item, createdBy, addedAt: item.addedAt ?? clock.now().toISOString() }
+    const result = await repository.add(stored)
+    return {
+      ...result,
+      conflict: result.created === false && catalogById[indicatorId] !== undefined,
+    }
+  }
+
+  /**
+   * Remove an indicator.
+   *
+   * @param {string} indicatorId - indicator id.
+   * @returns {Promise<{ status: 'removed'|'notFound' }>} result.
+   */
+  async function remove(indicatorId) {
+    const status = await repository.remove(indicatorId)
+    return { status }
+  }
+
+  /**
+   * Patch one indicator.
+   *
+   * @param {string} indicatorId - indicator id.
+   * @param {object} patch - fields to change.
+   * @returns {Promise<{ item?: object, status: 'updated'|'notFound' }>} result.
+   */
+  async function update(indicatorId, patch) {
+    const item = await repository.update(indicatorId, patch)
+    return item === undefined ? { status: 'notFound' } : { status: 'updated', item }
+  }
+
+  /**
+   * Reorder the list by explicit ids.
+   *
+   * @param {string[]} orderedIds - the desired order.
+   * @returns {Promise<{ items: object[], missing: string[] }>} result.
+   */
+  async function reorder(orderedIds) {
+    const existing = new Set((await repository.list()).map((item) => item.indicatorId))
+    const missing = orderedIds.filter((id) => !existing.has(id))
+    await Promise.all(
+      orderedIds
+        .filter((id) => existing.has(id))
+        .map((id, index) => repository.update(id, { order: index })),
+    )
+    return { items: await list(), missing }
+  }
+
+  return { list, add, remove, update, reorder }
+}