@zerotal/monitor 1.8.1 → 1.10.0

package/CHANGELOG.md

@@ -8,6 +8,43 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.10.0] — 2026-08-30
+
+### Fixed
+
+- **`MonitorStore` options no longer overwrite their own defaults with `undefined`.**
+  The constructor applied `?? 100`-style defaults and then spread `...opts` **after**
+  them, and object spread copies own properties even when their value is `undefined`.
+  So `new MonitorStore({ retentionDays: cfg.retentionDays })` with an unset config put
+  `undefined` straight back over the 7, and `prune()` computed a cutoff of
+  `Date.now() - undefined * DAY_MS` — `NaN`, which prunes nothing and reports nothing.
+  Spreading last is what made every `??` in that constructor decorative.
+
+  The caller's options now go first and the defaults fill the gaps, which is the
+  ordering `Socket`'s constructor already documents at length for the same reason.
+
+## [1.9.0] — 2026-08-29
+
+### Added
+
+- **The snapshot shape is documented.** **Export JSON** hands you a `MonitorSnapshot` — the whole
+  panel for a range, as data — and none of the forty-odd row types it is built from was named
+  anywhere. `docs/monitor.md` now maps every field to its row type, which is what you need to
+  post one somewhere, diff two of them, or drive an alerting integration off it rather than off
+  the built-in thresholds.
+
+- **Section contributions can be typed.** `MonitorSection`, `MonitorSectionData`, `MonitorStat`,
+  `MonitorTable`, `MonitorTableColumn` and `MonitorRow` are documented. Declaring the host's
+  shape locally stays the recommended path — it is what keeps a contributing package free of any
+  dependency on the monitor — but a large `resolve` is better served by a typo in a column key
+  being a compile error than a blank cell.
+
+### Changed
+
+- **INTERNAL: `MonitorLayout`, `MonitorPage` and `MonitorPanelHost` are marked `@internal`.**
+  The panel's own shell. Still exported, still working; a contributor pushes a section into the
+  host binding rather than constructing any of them.
+
 ## [1.6.0] — 2026-08-15
 
 ### Fixed

package/api-surface.md

@@ -286,37 +286,32 @@ interface ModelStat = {
 }
 
 interface MonitorConfigShape = {
-  accent?: string
-  alertCooldownMs?: number
-  alertThresholds?: AlertThresholds
-  alertWebhook?: string
-  alerts?: boolean
-  apdexTargetMs?: number
-  auth?: (user: unknown) => boolean | Promise<boolean>
-  capturePayloads?: boolean
-  deploy?: string
-  metrics?: boolean
-  metricsPath?: string
-  path?: string
-  payloadMaxBytes?: number
-  record?: boolean
-  refreshMs?: number
-  region?: string
-  retentionDays?: number
-  retentionMode?: RetentionMode
-  sections?: Record<string, boolean>
-  slowQueryMs?: number
-  slowRequestMs?: number
-  snapshotCacheMs?: number
-  storage?: string
-  subtitle?: string
-  title?: string
-  zerotalVersion?: string
-}
-
-interface MonitorPanelHost = {
-  enabled: (id: string) => boolean
-  section: (section: MonitorSection) => void
+  accent?: string | undefined
+  alertCooldownMs?: number | undefined
+  alertThresholds?: AlertThresholds | undefined
+  alertWebhook?: string | undefined
+  alerts?: boolean | undefined
+  apdexTargetMs?: number | undefined
+  auth?: ((user: unknown) => boolean | Promise<boolean>) | undefined
+  capturePayloads?: boolean | undefined
+  deploy?: string | undefined
+  metrics?: boolean | undefined
+  metricsPath?: string | undefined
+  path?: string | undefined
+  payloadMaxBytes?: number | undefined
+  record?: boolean | undefined
+  refreshMs?: number | undefined
+  region?: string | undefined
+  retentionDays?: number | undefined
+  retentionMode?: RetentionMode | undefined
+  sections?: Record<string, boolean> | undefined
+  slowQueryMs?: number | undefined
+  slowRequestMs?: number | undefined
+  snapshotCacheMs?: number | undefined
+  storage?: string | undefined
+  subtitle?: string | undefined
+  title?: string | undefined
+  zerotalVersion?: string | undefined
 }
 
 interface MonitorSection = {
@@ -391,16 +386,16 @@ interface MonitorStat = {
 }
 
 interface MonitorStoreOptions = {
-  apdexTargetMs?: number
-  deploy?: string
-  region?: string
-  retentionDays?: number
-  retentionMode?: RetentionMode
-  slowQueryMs?: number
-  slowRequestMs?: number
-  snapshotCacheMs?: number
-  storage?: string
-  zerotalVersion?: string
+  apdexTargetMs?: number | undefined
+  deploy?: string | undefined
+  region?: string | undefined
+  retentionDays?: number | undefined
+  retentionMode?: RetentionMode | undefined
+  slowQueryMs?: number | undefined
+  slowRequestMs?: number | undefined
+  snapshotCacheMs?: number | undefined
+  storage?: string | undefined
+  zerotalVersion?: string | undefined
 }
 
 interface MonitorTable = {
@@ -530,30 +525,30 @@ interface RequestSpan = {
 interface ResolvedMonitorConfig = {
   accent: string
   alertCooldownMs: number
-  alertThresholds?: AlertThresholds
-  alertWebhook?: string
+  alertThresholds?: AlertThresholds | undefined
+  alertWebhook?: string | undefined
   alerts: boolean
   apdexTargetMs: number
   auth: (user: unknown) => boolean | Promise<boolean>
   capturePayloads: boolean
-  deploy?: string
+  deploy?: string | undefined
   metrics: boolean
   metricsPath: string
   path: string
   payloadMaxBytes: number
   record: boolean
   refreshMs: number
-  region?: string
+  region?: string | undefined
   retentionDays: number
   retentionMode: RetentionMode
-  sections?: Record<string, boolean>
+  sections?: Record<string, boolean> | undefined
   slowQueryMs: number
   slowRequestMs: number
   snapshotCacheMs: number
   storage: string
   subtitle: string
   title: string
-  zerotalVersion?: string
+  zerotalVersion?: string | undefined
 }
 
 interface RouteDetail = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/monitor",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,14 +30,14 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.8.1",
-    "@zerotal/flow-ui": "1.8.1",
-    "@zerotal/flow": "1.8.1"
+    "@zerotal/core": "1.10.0",
+    "@zerotal/flow-ui": "1.10.0",
+    "@zerotal/flow": "1.10.0"
   },
   "devDependencies": {
-    "@zerotal/queue": "1.8.1",
-    "@zerotal/scheduler": "1.8.1",
-    "@zerotal/telemetry": "1.8.1"
+    "@zerotal/queue": "1.10.0",
+    "@zerotal/scheduler": "1.10.0",
+    "@zerotal/telemetry": "1.10.0"
   },
   "peerDependencies": {
     "@zerotal/queue": "^1.0.0",

package/src/MonitorStore.ts

@@ -12,6 +12,7 @@
  * A retention policy (`prune`) deletes or archives data past the configured
  * window, and `wipe` clears everything on demand from the panel.
  */
+import type { Resolved } from "@zerotal/core";
 import { percentile } from "./store/RingBuffer.ts";
 import { MonitorDb } from "./store/MonitorDb.ts";
 import {
@@ -107,25 +108,25 @@ interface ReqSample {
 }
 
 export interface MonitorStoreOptions {
-  apdexTargetMs?: number;
-  slowQueryMs?: number;
-  zerotalVersion?: string;
-  region?: string;
-  deploy?: string;
+  apdexTargetMs?: number | undefined;
+  slowQueryMs?: number | undefined;
+  zerotalVersion?: string | undefined;
+  region?: string | undefined;
+  deploy?: string | undefined;
   /** SQLite path. `:memory:` (default) for tests; a file path for persistence. */
-  storage?: string;
+  storage?: string | undefined;
   /** Days of history to keep before pruning. Default: 7. */
-  retentionDays?: number;
+  retentionDays?: number | undefined;
   /** What to do with data past retention: delete it or move it to the archive. Default: `delete`. */
-  retentionMode?: RetentionMode;
+  retentionMode?: RetentionMode | undefined;
   /** Requests at/above this many ms count as "slow". Default: 1000. */
-  slowRequestMs?: number;
+  slowRequestMs?: number | undefined;
   /**
    * Cache built snapshots for this many ms, keyed by range. De-dupes overlapping
    * builds (panel poll + Prometheus scrape + alert loop all hit "live"). Mutating
    * actions invalidate it. Default: 0 (off) — the provider enables it in production.
    */
-  snapshotCacheMs?: number;
+  snapshotCacheMs?: number | undefined;
 }
 
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -139,22 +140,32 @@ export class MonitorStore {
   private readonly _snapTtlMs: number;
   private readonly _snapCache = new Map<MonitorRange, { at: number; snap: MonitorSnapshot }>();
 
-  private readonly _opts: Required<
+  private readonly _opts: Resolved<
     Pick<
       MonitorStoreOptions,
       "apdexTargetMs" | "slowQueryMs" | "slowRequestMs" | "retentionDays" | "retentionMode"
     >
   > &
-    MonitorStoreOptions;
+    Omit<
+      MonitorStoreOptions,
+      "apdexTargetMs" | "slowQueryMs" | "slowRequestMs" | "retentionDays" | "retentionMode"
+    >;
 
   constructor(opts: MonitorStoreOptions = {}) {
+    // The caller's options go FIRST, then the defaults fill the gaps — the same
+    // ordering, for the same reason, as `Socket`'s constructor documents at length.
+    // Object spread copies own properties even when their value is `undefined`, so
+    // `new MonitorStore({ retentionDays: cfg.retentionDays })` with an unset config
+    // put `undefined` straight back over the 7 and `prune()` then computed a cutoff
+    // of `Date.now() - undefined * DAY_MS` — NaN, which deletes nothing and reports
+    // nothing. Spreading last is what made the `??` above decorative.
     this._opts = {
+      ...opts,
       apdexTargetMs: opts.apdexTargetMs ?? 100,
       slowQueryMs: opts.slowQueryMs ?? 100,
       slowRequestMs: opts.slowRequestMs ?? 1000,
       retentionDays: opts.retentionDays ?? 7,
       retentionMode: opts.retentionMode ?? "delete",
-      ...opts,
     };
     this._snapTtlMs = Math.max(0, opts.snapshotCacheMs ?? 0);
     this._db = new MonitorDb(opts.storage ?? ":memory:");

package/src/config.ts

@@ -13,91 +13,91 @@ import type { AlertThresholds } from "./alerting.ts";
 
 export interface MonitorConfigShape {
   /** URL prefix the panel mounts at. Default: `/monitor`. */
-  path?: string;
+  path?: string | undefined;
   /** Browser tab title / sidebar heading. Default: `Super Panel`. */
-  title?: string;
+  title?: string | undefined;
   /** Sub-label under the title. Default: `Zerotal Ops`. */
-  subtitle?: string;
+  subtitle?: string | undefined;
   /**
    * Authorization gate. Receives the authenticated user (or undefined) and
    * must return true to allow access. Default: allow only outside production.
    */
-  auth?: (user: unknown) => boolean | Promise<boolean>;
+  auth?: ((user: unknown) => boolean | Promise<boolean>) | undefined;
   /** Install the recorder middleware to capture live request data. Default: true. */
-  record?: boolean;
+  record?: boolean | undefined;
   /** Auto-refresh cadence in milliseconds while "Live" is on. Default: 3000. */
-  refreshMs?: number;
+  refreshMs?: number | undefined;
   /** Apdex satisfaction threshold (T) in ms. Default: 100. */
-  apdexTargetMs?: number;
+  apdexTargetMs?: number | undefined;
   /** Queries at/above this many ms count as "slow". Default: 100. */
-  slowQueryMs?: number;
+  slowQueryMs?: number | undefined;
   /** Requests at/above this many ms count as "slow" (Slow Requests widget). Default: 1000. */
-  slowRequestMs?: number;
+  slowRequestMs?: number | undefined;
   /**
    * Capture request/response headers and bodies on each request (Telescope-style),
    * shown in the request trace. Off by default — it buffers bodies and is
    * privacy-sensitive. Sensitive headers (authorization/cookie) and body keys
    * (password/token/secret/…) are redacted automatically.
    */
-  capturePayloads?: boolean;
+  capturePayloads?: boolean | undefined;
   /** Truncate captured request/response bodies to this many bytes. Default: 65536. */
-  payloadMaxBytes?: number;
+  payloadMaxBytes?: number | undefined;
   /**
    * Cache built snapshots for this many ms, keyed by range, so overlapping reads
    * (panel poll + Prometheus scrape + alert loop) share one build. Mutating actions
    * invalidate it. Default: 1000. Set `0` to always build fresh.
    */
-  snapshotCacheMs?: number;
+  snapshotCacheMs?: number | undefined;
   /**
    * SQLite file the panel persists to, so history survives restarts and the
    * 1h/24h/7d ranges trace real data. Default: `storage/monitor.sqlite`. Use
    * `:memory:` for an ephemeral, in-process store.
    */
-  storage?: string;
+  storage?: string | undefined;
   /** Days of history to keep before pruning. Default: 7. */
-  retentionDays?: number;
+  retentionDays?: number | undefined;
   /** What to do with data past retention: `delete` it or `archive` it. Default: `delete`. */
-  retentionMode?: RetentionMode;
+  retentionMode?: RetentionMode | undefined;
   /**
    * Expose a Prometheus text-exposition endpoint. Default: `false` (opt-in).
    * The endpoint is unauthenticated (a scraper can't satisfy user-auth), so it
    * ships off; enable it only when you protect `metricsPath` at the network
    * layer (firewall/ingress) or scope it to a private interface.
    */
-  metrics?: boolean;
+  metrics?: boolean | undefined;
   /** Path for the Prometheus endpoint. Default: `/metrics`. Protect it at the network layer. */
-  metricsPath?: string;
+  metricsPath?: string | undefined;
   /** Evaluate threshold alerts on a short interval. Default: `true`. */
-  alerts?: boolean;
+  alerts?: boolean | undefined;
   /** Alert thresholds (error rate, queue backlog, p95, rollbacks). */
-  alertThresholds?: AlertThresholds;
+  alertThresholds?: AlertThresholds | undefined;
   /**
    * Minimum gap (ms) before the same alert can fire again after it recovers and
    * re-breaches. Stops an oscillating metric from re-paging / re-flooding the feed
    * for one ongoing issue. Default: 30 min. Set `0` to fire on every fresh breach.
    */
-  alertCooldownMs?: number;
+  alertCooldownMs?: number | undefined;
   /**
    * Slack-compatible webhook URL. When set, every newly-firing alert is POSTed to
    * it as JSON (`{ text, level, title, detail }`) so alerts page someone instead of
    * only lighting up the panel. Dependency-free (uses `fetch`); delivery is
    * best-effort. For richer routing, register a handler with `onAlert()` instead.
    */
-  alertWebhook?: string;
+  alertWebhook?: string | undefined;
   /** Accent colour (hex) for the panel chrome. Default: Zerotal orange. */
-  accent?: string;
+  accent?: string | undefined;
   /** Version string shown in the System footer. */
-  zerotalVersion?: string;
+  zerotalVersion?: string | undefined;
   /** Region label shown in the System footer. */
-  region?: string;
+  region?: string | undefined;
   /** Deploy SHA shown in the System footer. */
-  deploy?: string;
+  deploy?: string | undefined;
   /**
    * Switch contributed sections off by id — `{ scheduler: false }` keeps the
    * scheduler installed but drops its section from the panel. Anything absent
    * here is on.
    */
-  sections?: Record<string, boolean>;
+  sections?: Record<string, boolean> | undefined;
 }
 
 export interface ResolvedMonitorConfig extends MonitorConfigShape {

package/src/panel.ts

@@ -99,6 +99,8 @@ export interface MonitorSection {
  *
  * Contributors should declare their own minimal copy of the members they use
  * rather than importing this type, so they depend on this package not at all.
+ *
+ * @internal
  */
 export interface MonitorPanelHost {
   /**

package/src/ui/MonitorLayout.tsx

@@ -31,6 +31,7 @@ const MONITOR_TOKENS = `
 }
 `.trim();
 
+/** @internal */
 export class MonitorLayout extends Layout {
   static override get head(): string {
     return flowUiHead("Zerotal · Monitor", { tokensCss: MONITOR_TOKENS });

package/src/ui/MonitorPage.tsx

@@ -121,6 +121,8 @@ const FEED_PER_PAGE = 12;
  * `super-panel.html` built on Flow. Eight tabs (Overview, Requests,
  * Exceptions, Queues, Mail, Database, Cache, System) render from a live
  * {@link MonitorSnapshot}; interactions round-trip over the Flow WebSocket.
+ *
+ * @internal
  */
 export class MonitorPage extends Component {
   static layout = MonitorLayout;