@dudousxd/nestjs-catalog-react 0.19.0-preview.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,4 @@
1
- import type { CatalogTraceList, TraceQuery } from '@dudousxd/nestjs-catalog';
1
+ import type { CatalogTrace, CatalogTraceList, TraceQuery } from '@dudousxd/nestjs-catalog';
2
2
  import { Upload } from 'lucide-react';
3
3
  /**
4
4
  * Where this screen gets its traces.
@@ -10,6 +10,16 @@ import { Upload } from 'lucide-react';
10
10
  */
11
11
  export interface CatalogTraceSource {
12
12
  listTraces(query: TraceQuery): Promise<CatalogTraceList>;
13
+ /**
14
+ * One trace, with the payloads the list leaves in the database.
15
+ *
16
+ * Optional for the same reason the whole source is discovered rather than
17
+ * declared: a host that has not updated its client still gets a working
18
+ * screen. Without it the steps render from what the list carried, which is
19
+ * every step, its timing and its error — everything except the one payload
20
+ * line per step that `summarise` writes.
21
+ */
22
+ getTrace?(id: string): Promise<CatalogTrace>;
13
23
  }
14
24
  /**
15
25
  * Resolves the trace source from whatever client the host provided.
@@ -29,8 +29,17 @@ export function useTraceSource(explicit) {
29
29
  const candidate = Reflect.get(client, 'listTraces');
30
30
  if (typeof candidate !== 'function')
31
31
  return undefined;
32
+ const one = Reflect.get(client, 'getTrace');
32
33
  return {
33
34
  listTraces: (query) => Promise.resolve(candidate.call(client, query)).then(toTraceList),
35
+ // Discovered separately from `listTraces`, because the two arrived in
36
+ // different versions: a host pinned to a client that has the list and not
37
+ // this one is a supported state, and the steps still render without it.
38
+ ...(typeof one === 'function'
39
+ ? {
40
+ getTrace: (id) => Promise.resolve(one.call(client, id)).then(toTrace),
41
+ }
42
+ : {}),
34
43
  };
35
44
  }, [client, explicit]);
36
45
  }
@@ -70,6 +79,20 @@ function isTrace(value) {
70
79
  typeof Reflect.get(value, 'id') === 'string' &&
71
80
  Array.isArray(Reflect.get(value, 'spans')));
72
81
  }
82
+ /**
83
+ * One trace, validated the same way the list's are.
84
+ *
85
+ * Same reason as {@link toTraceList}: it came back through a method nobody
86
+ * type-checked, and the steps pane is where somebody is reading a payload
87
+ * closely enough that a silently malformed one would mislead rather than
88
+ * merely look wrong.
89
+ */
90
+ function toTrace(value) {
91
+ if (!isTrace(value)) {
92
+ throw new Error('The trace endpoint answered with something that is not a trace.');
93
+ }
94
+ return value;
95
+ }
73
96
  function numberOr(value, fallback) {
74
97
  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
75
98
  }
@@ -221,16 +244,54 @@ export function TraceExplorer({ source } = {}) {
221
244
  // throws. Nested providers are a no-op, so the shared case costs nothing.
222
245
  return (_jsx(TooltipProvider, { children: _jsxs("div", { className: "space-y-4", children: [_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [OUTCOME_FILTERS.map((filter) => (_jsx("button", { type: "button", onClick: () => setOutcome(filter.id), className: cn('rounded-md border px-2.5 py-1 text-xs transition-colors', filter.id === outcome
223
246
  ? 'border-zinc-400 bg-zinc-100 text-zinc-950 dark:border-zinc-600 dark:bg-zinc-800 dark:text-zinc-50'
224
- : cn(RULE, 'hover:bg-zinc-50 dark:hover:bg-zinc-800/60', MUTED)), children: filter.label }, filter.id || 'all'))), _jsx(Tooltip, { content: "Re-read the trail now", children: _jsx("button", { type: "button", onClick: () => void refetch(), "aria-label": "Refresh traces", className: cn('ml-auto rounded-md border p-1.5 transition-colors', RULE, 'hover:bg-zinc-50 dark:hover:bg-zinc-800/60'), children: _jsx(RefreshCw, { size: 13, className: cn(isFetching && 'animate-spin') }) }) })] }), isLoading && (_jsx("p", { className: cn('py-10 text-center font-mono text-sm', MUTED), children: "Reassembling the trail\u2026" })), error && (_jsx("p", { className: cn('rounded-lg border border-red-300 bg-red-50 px-4 py-3 text-sm text-red-700', 'dark:border-red-900 dark:bg-red-950/40 dark:text-red-300'), children: error instanceof Error ? error.message : String(error) })), data && data.traces.length === 0 && (_jsx("p", { className: cn('rounded-lg border border-dashed px-4 py-12 text-center text-sm', RULE, MUTED), children: "No trace matches. Every trace is one snapshot id \u2014 publish something, or run a connector, and its whole story appears here." })), _jsx("div", { className: "space-y-2", children: (data?.traces ?? []).map((trace) => (_jsx(TraceCard, { trace: trace, expanded: open === trace.id, onToggle: () => setOpen(open === trace.id ? null : trace.id) }, trace.id))) }), data && data.total > data.traces.length && (_jsxs("p", { className: cn('text-center font-mono text-[10px]', MUTED), children: ["Showing ", data.traces.length, " of ", data.total, " traces."] })), data && data.unlinked.length > 0 && _jsx(Unlinked, { list: data.unlinked })] }) }));
247
+ : cn(RULE, 'hover:bg-zinc-50 dark:hover:bg-zinc-800/60', MUTED)), children: filter.label }, filter.id || 'all'))), _jsx(Tooltip, { content: "Re-read the trail now", children: _jsx("button", { type: "button", onClick: () => void refetch(), "aria-label": "Refresh traces", className: cn('ml-auto rounded-md border p-1.5 transition-colors', RULE, 'hover:bg-zinc-50 dark:hover:bg-zinc-800/60'), children: _jsx(RefreshCw, { size: 13, className: cn(isFetching && 'animate-spin') }) }) })] }), isLoading && (_jsx("p", { className: cn('py-10 text-center font-mono text-sm', MUTED), children: "Reassembling the trail\u2026" })), error && (_jsx("p", { className: cn('rounded-lg border border-red-300 bg-red-50 px-4 py-3 text-sm text-red-700', 'dark:border-red-900 dark:bg-red-950/40 dark:text-red-300'), children: error instanceof Error ? error.message : String(error) })), data && data.traces.length === 0 && (_jsx("p", { className: cn('rounded-lg border border-dashed px-4 py-12 text-center text-sm', RULE, MUTED), children: "No trace matches. Every trace is one snapshot id \u2014 publish something, or run a connector, and its whole story appears here." })), _jsx("div", { className: "space-y-2", children: (data?.traces ?? []).map((trace) => (_jsx(TraceCard, { trace: trace, source: traces, expanded: open === trace.id, onToggle: () => setOpen(open === trace.id ? null : trace.id) }, trace.id))) }), data && data.total > data.traces.length && (_jsxs("p", { className: cn('text-center font-mono text-[10px]', MUTED), children: ["Showing ", data.traces.length, " of ", data.total, " traces."] })), data && data.unlinked.length > 0 && _jsx(Unlinked, { list: data.unlinked })] }) }));
248
+ }
249
+ /**
250
+ * The steps of one expanded trace.
251
+ *
252
+ * Rendered only while the card is open, which is the whole optimisation: a
253
+ * screen showing fifty collapsed cards makes none of these requests, and the
254
+ * list it drew them from never carried the payloads to begin with.
255
+ *
256
+ * The list's spans are the steps — every one of them, in order, with its timing
257
+ * and its error. What they do not carry is the event payload, which is the one
258
+ * line per step {@link summarise} writes and the reason a page of traces would
259
+ * otherwise be megabytes of JSON nobody looked at. So opening a card fetches
260
+ * the trace that has them.
261
+ *
262
+ * Those spans are drawn immediately and replaced when the fetch lands, rather
263
+ * than a spinner standing in for them. Every step, its order and its error are
264
+ * already known; blanking a pane that can already answer "which step failed" to
265
+ * wait for one line of payload would be slower exactly where it matters. If the
266
+ * fetch fails, or the host's client predates `getTrace`, that is simply where it
267
+ * stays — one line per step poorer, and still the whole story.
268
+ */
269
+ function TraceSteps({ trace, source }) {
270
+ const fetchOne = source.getTrace;
271
+ const { data, isFetching } = useQuery({
272
+ queryKey: ['catalog', 'trace', trace.id],
273
+ queryFn: () => {
274
+ if (!fetchOne)
275
+ throw new Error('This client cannot fetch a single trace.');
276
+ return fetchOne(trace.id);
277
+ },
278
+ enabled: typeof fetchOne === 'function',
279
+ // The payloads of a finished load do not change. A running one keeps
280
+ // gaining steps, and the list underneath is already re-polling, so this
281
+ // follows it rather than holding a stale pane open beside a fresh card.
282
+ staleTime: OUTCOMES[trace.outcome].settled ? Number.POSITIVE_INFINITY : 10_000,
283
+ });
284
+ const spans = data?.spans ?? trace.spans;
285
+ return (_jsxs("div", { className: "mt-2 space-y-1 border-t border-zinc-100 pt-2 dark:border-zinc-800", children: [spans.map((span) => (_jsx(Step, { span: span, coarse: trace.coarse }, span.id))), isFetching && data === undefined && (_jsxs("p", { className: cn('flex items-center gap-1.5 font-mono text-[10px]', MUTED), children: [_jsx(LoaderCircle, { size: 11, className: "animate-spin" }), "loading payloads"] }))] }));
225
286
  }
226
- function TraceCard({ trace, expanded, onToggle, }) {
287
+ function TraceCard({ trace, source, expanded, onToggle, }) {
227
288
  const outcome = OUTCOMES[trace.outcome];
228
289
  const OutcomeIcon = outcome.icon;
229
290
  return (_jsxs("div", { className: cn('rounded-lg border border-l-2 p-3', RULE, PANEL, outcome.edge), children: [_jsxs("div", { className: "flex flex-wrap items-center gap-x-2 gap-y-1", children: [_jsx(Tooltip, { content: outcome.meaning, children: _jsxs("span", { className: cn('flex cursor-help items-center gap-1.5 rounded-md border px-1.5 py-0.5 text-[11px]', outcome.chip), children: [_jsx(OutcomeIcon, { size: 11, className: cn(trace.outcome === 'running' && 'animate-spin') }), outcome.label] }) }), _jsx("span", { className: "font-mono text-[11px]", children: trace.id }), trace.typeName && (_jsx("span", { className: cn('font-mono text-[10px]', MUTED), children: trace.typeName })), trace.connectorName && (_jsxs("span", { className: "text-[11px] text-zinc-600 dark:text-zinc-300", children: ["via ", trace.connectorName] })), _jsx("span", { className: cn('ml-auto font-mono text-[10px]', MUTED), children: new Date(trace.startedAt).toLocaleString() })] }), _jsxs("div", { className: cn('mt-1 flex flex-wrap gap-x-3 font-mono text-[10px]', MUTED), children: [_jsx(Tooltip, { content: outcome.settled
230
291
  ? 'Start of the first event to the end of the last.'
231
292
  : 'Time since it started. It has not reported an end, so this keeps growing.', children: _jsx("span", { className: "cursor-help", children: outcome.settled
232
293
  ? formatDuration(trace.durationMs ?? 0)
233
- : `${formatSince(trace.startedAt)} so far` }) }), _jsxs("span", { children: [trace.eventCount, " events"] }), trace.rowsCommitted !== undefined && _jsxs("span", { children: [trace.rowsCommitted, " rows served"] }), trace.principalId && _jsx("span", { children: trace.principalId }), trace.failureCount > 0 && trace.outcome !== 'failed' && (_jsx(Tooltip, { content: "An earlier attempt on this same snapshot id failed. A retry reuses the id, so both attempts are in this one story.", children: _jsxs("span", { className: "cursor-help text-amber-600", children: [trace.failureCount, " earlier failure", trace.failureCount === 1 ? '' : 's'] }) })), !outcome.settled && _jsxs("span", { children: ["last event ", formatSince(trace.lastEventAt), " ago"] })] }), _jsx(Waterfall, { trace: trace }), trace.error && (_jsx("p", { className: cn('mt-2 rounded-md border border-red-300 bg-red-50 px-2.5 py-1.5 font-mono text-[11px] leading-snug text-red-700', 'dark:border-red-900 dark:bg-red-950/40 dark:text-red-300'), children: trace.error })), _jsxs("button", { type: "button", onClick: onToggle, className: cn('mt-2 flex items-center gap-1 text-[11px] transition-colors', MUTED, 'hover:text-zinc-950 dark:hover:text-zinc-50'), children: [expanded ? _jsx(ChevronDown, { size: 12 }) : _jsx(ChevronRight, { size: 12 }), expanded ? 'Hide steps' : `${trace.spans.length} steps`] }), expanded && (_jsx("div", { className: "mt-2 space-y-1 border-t border-zinc-100 pt-2 dark:border-zinc-800", children: trace.spans.map((span) => (_jsx(Step, { span: span, coarse: trace.coarse }, span.id))) }))] }));
294
+ : `${formatSince(trace.startedAt)} so far` }) }), _jsxs("span", { children: [trace.eventCount, " events"] }), trace.rowsCommitted !== undefined && _jsxs("span", { children: [trace.rowsCommitted, " rows served"] }), trace.principalId && _jsx("span", { children: trace.principalId }), trace.failureCount > 0 && trace.outcome !== 'failed' && (_jsx(Tooltip, { content: "An earlier attempt on this same snapshot id failed. A retry reuses the id, so both attempts are in this one story.", children: _jsxs("span", { className: "cursor-help text-amber-600", children: [trace.failureCount, " earlier failure", trace.failureCount === 1 ? '' : 's'] }) })), !outcome.settled && _jsxs("span", { children: ["last event ", formatSince(trace.lastEventAt), " ago"] })] }), _jsx(Waterfall, { trace: trace }), trace.error && (_jsx("p", { className: cn('mt-2 rounded-md border border-red-300 bg-red-50 px-2.5 py-1.5 font-mono text-[11px] leading-snug text-red-700', 'dark:border-red-900 dark:bg-red-950/40 dark:text-red-300'), children: trace.error })), _jsxs("button", { type: "button", onClick: onToggle, className: cn('mt-2 flex items-center gap-1 text-[11px] transition-colors', MUTED, 'hover:text-zinc-950 dark:hover:text-zinc-50'), children: [expanded ? _jsx(ChevronDown, { size: 12 }) : _jsx(ChevronRight, { size: 12 }), expanded ? 'Hide steps' : `${trace.spans.length} steps`] }), expanded && _jsx(TraceSteps, { trace: trace, source: source })] }));
234
295
  }
235
296
  /**
236
297
  * The waterfall.