@dudousxd/nestjs-catalog-react 0.15.0 → 0.16.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.
@@ -4,6 +4,7 @@ import { ArrowLeft, ArrowRight, ArrowUpRight, Eye, EyeOff, RotateCcw, Search, Un
4
4
  import { useMemo, useState } from 'react';
5
5
  import { CoverageLedger } from './CoverageLedger';
6
6
  import { EditableField } from './EditableField';
7
+ import { LoadExpectationSection } from './LoadExpectationSection';
7
8
  import { cn } from './cn';
8
9
  import { catalogQueryKeys, useCatalogClient } from './context';
9
10
  import { freshnessOf, isWorthFlagging } from './freshness';
@@ -115,7 +116,7 @@ function Stat({ label, value }) {
115
116
  }
116
117
  function TypeDetail({ type, types, explorerHref, onPatchType, onPatchProperty, onNavigate, }) {
117
118
  const visible = type.properties.filter((p) => !p.hidden).length;
118
- return (_jsxs("div", { className: "mx-auto max-w-5xl px-8 py-8", children: [_jsxs("div", { className: "flex flex-wrap items-start justify-between gap-4", children: [_jsxs("div", { className: "min-w-0", children: [_jsxs("div", { className: "flex items-baseline gap-2", children: [_jsx("span", { className: "text-2xl leading-none", children: type.icon ?? '◈' }), _jsx(EditableField, { label: "display name", value: type.displayName, onSave: (displayName) => onPatchType({ displayName }), className: "text-2xl font-semibold tracking-tight", inputClassName: "text-2xl font-semibold tracking-tight" })] }), _jsxs("div", { className: cn('mt-1.5 flex flex-wrap items-center gap-x-3 gap-y-1 pl-1 font-mono text-[11px]', MUTED), children: [_jsx("span", { children: type.name }), _jsx("span", { "aria-hidden": true, children: "\u00B7" }), _jsx("span", { children: type.tableName }), _jsx("span", { "aria-hidden": true, children: "\u00B7" }), _jsxs("span", { children: ["pk ", type.primaryKey.join(', ') || 'none'] }), _jsx("span", { "aria-hidden": true, children: "\u00B7" }), _jsxs("span", { children: [visible, " of ", type.properties.length, " shown"] })] })] }), explorerHref && (_jsxs("a", { href: explorerHref(type.name), className: cn('flex items-center gap-1.5 rounded-md bg-zinc-950 px-3 py-2 text-xs text-zinc-50', 'transition-colors hover:bg-zinc-800 dark:bg-zinc-100 dark:text-zinc-950 dark:hover:bg-zinc-300'), children: ["Open ", type.pluralDisplayName, _jsx(ArrowUpRight, { size: 13 })] }))] }), _jsx("div", { className: "mt-5 border-l-2 border-sky-200 pl-4 dark:border-sky-900", children: _jsx(RichTextField, { label: "description", value: type.description ?? '', placeholder: "No one has written down what this type means yet.", onSave: (description) => onPatchType({ description }), className: cn('text-sm leading-relaxed', SECONDARY) }) }), _jsxs("div", { className: "mt-4 flex flex-wrap items-center gap-2", children: [_jsx(FieldChip, { label: "Group", value: type.group, onSave: (group) => onPatchType({ group }) }), _jsx(FieldChip, { label: "Plural", value: type.pluralDisplayName, onSave: (pluralDisplayName) => onPatchType({ pluralDisplayName }) }), _jsx(FieldChip, { label: "Icon", value: type.icon ?? '', onSave: (icon) => onPatchType({ icon }) })] }), _jsxs("section", { className: "mt-10", children: [_jsx(SectionHeading, { title: "Properties", note: "The column and its SQL type are read from the ORM. The label, description and unit are yours." }), _jsx("div", { className: cn('overflow-hidden rounded-lg border', RULE, PANEL), children: _jsx(PropertyTable, { properties: type.properties, onPatchProperty: onPatchProperty }) })] }), _jsx(LinkSection, { type: type, types: types, onPatchProperty: onPatchProperty, onNavigate: onNavigate })] }));
119
+ return (_jsxs("div", { className: "mx-auto max-w-5xl px-8 py-8", children: [_jsxs("div", { className: "flex flex-wrap items-start justify-between gap-4", children: [_jsxs("div", { className: "min-w-0", children: [_jsxs("div", { className: "flex items-baseline gap-2", children: [_jsx("span", { className: "text-2xl leading-none", children: type.icon ?? '◈' }), _jsx(EditableField, { label: "display name", value: type.displayName, onSave: (displayName) => onPatchType({ displayName }), className: "text-2xl font-semibold tracking-tight", inputClassName: "text-2xl font-semibold tracking-tight" })] }), _jsxs("div", { className: cn('mt-1.5 flex flex-wrap items-center gap-x-3 gap-y-1 pl-1 font-mono text-[11px]', MUTED), children: [_jsx("span", { children: type.name }), _jsx("span", { "aria-hidden": true, children: "\u00B7" }), _jsx("span", { children: type.tableName }), _jsx("span", { "aria-hidden": true, children: "\u00B7" }), _jsxs("span", { children: ["pk ", type.primaryKey.join(', ') || 'none'] }), _jsx("span", { "aria-hidden": true, children: "\u00B7" }), _jsxs("span", { children: [visible, " of ", type.properties.length, " shown"] })] })] }), explorerHref && (_jsxs("a", { href: explorerHref(type.name), className: cn('flex items-center gap-1.5 rounded-md bg-zinc-950 px-3 py-2 text-xs text-zinc-50', 'transition-colors hover:bg-zinc-800 dark:bg-zinc-100 dark:text-zinc-950 dark:hover:bg-zinc-300'), children: ["Open ", type.pluralDisplayName, _jsx(ArrowUpRight, { size: 13 })] }))] }), _jsx("div", { className: "mt-5 border-l-2 border-sky-200 pl-4 dark:border-sky-900", children: _jsx(RichTextField, { label: "description", value: type.description ?? '', placeholder: "No one has written down what this type means yet.", onSave: (description) => onPatchType({ description }), className: cn('text-sm leading-relaxed', SECONDARY) }) }), _jsxs("div", { className: "mt-4 flex flex-wrap items-center gap-2", children: [_jsx(FieldChip, { label: "Group", value: type.group, onSave: (group) => onPatchType({ group }) }), _jsx(FieldChip, { label: "Plural", value: type.pluralDisplayName, onSave: (pluralDisplayName) => onPatchType({ pluralDisplayName }) }), _jsx(FieldChip, { label: "Icon", value: type.icon ?? '', onSave: (icon) => onPatchType({ icon }) })] }), _jsxs("section", { className: "mt-10", children: [_jsx(SectionHeading, { title: "Properties", note: "The column and its SQL type are read from the ORM. The label, description and unit are yours." }), _jsx("div", { className: cn('overflow-hidden rounded-lg border', RULE, PANEL), children: _jsx(PropertyTable, { properties: type.properties, onPatchProperty: onPatchProperty }) })] }), _jsx(LoadExpectationSection, { typeName: type.name, displayName: type.displayName }), _jsx(LinkSection, { type: type, types: types, onPatchProperty: onPatchProperty, onNavigate: onNavigate })] }));
119
120
  }
120
121
  /** What each kind actually says, for people who do not read `m:n` fluently. */
121
122
  const KIND_MEANING = {
@@ -0,0 +1,12 @@
1
+ /** The three, in the order the client package lists them, as a select understands them. */
2
+ export declare const DELETE_STRATEGIES: {
3
+ label: string;
4
+ hint: string;
5
+ value: "accepted" | "soft-deleted-at-source" | "periodic-full-reload";
6
+ }[];
7
+ export interface LoadExpectationSectionProps {
8
+ typeName: string;
9
+ /** What a person calls the type. Used in the sentences, which are about the type. */
10
+ displayName: string;
11
+ }
12
+ export declare function LoadExpectationSection({ typeName, displayName }: LoadExpectationSectionProps): import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,397 @@
1
+ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
2
+ import { DELETE_RECONCILIATION_STRATEGIES, isDeleteReconciliationStrategy, } from '@dudousxd/nestjs-catalog/client';
3
+ import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
4
+ import { Lock } from 'lucide-react';
5
+ import { useMemo, useState } from 'react';
6
+ import { cn } from './cn';
7
+ import { catalogQueryKeys, useCatalogClient, } from './context';
8
+ import { Button } from './ui/button';
9
+ import { DataTable } from './ui/data-table';
10
+ import { TextAreaField, TextField } from './ui/field';
11
+ import { SelectField } from './ui/select';
12
+ /**
13
+ * What a type promises about deletes and row counts, and the form that sets it.
14
+ *
15
+ * The section exists because of one state, and it is the empty one: a type with
16
+ * no delete strategy declared has its INCREMENTAL loads refused, and until this
17
+ * screen existed the only way to learn that was to run one and read the
18
+ * failure — or to have an engineer put the answer in `CATALOG_LOAD_EXPECTATIONS`
19
+ * and deploy. So the empty state is said in words rather than drawn as a blank
20
+ * field, and it is the first thing in the section.
21
+ *
22
+ * The other half is attribution. `because` is a sentence somebody is
23
+ * accountable for, so it is rendered as prose next to who wrote it and when —
24
+ * not as a value in the provenance table beside it, which would read as
25
+ * configuration and be skimmed like configuration.
26
+ */
27
+ const MUTED = 'text-zinc-400 dark:text-zinc-500';
28
+ const SECONDARY = 'text-zinc-500 dark:text-zinc-400';
29
+ const PANEL = 'bg-white dark:bg-zinc-900';
30
+ const RULE = 'border-zinc-200 dark:border-zinc-800';
31
+ const DANGER = 'text-rose-600 dark:text-rose-400';
32
+ /**
33
+ * What each strategy is called on screen, and what it means in one line.
34
+ *
35
+ * A `Record` over the union rather than a hand-written array of options, so the
36
+ * list of strategies has exactly one home — `DELETE_RECONCILIATION_STRATEGIES`
37
+ * in `@dudousxd/nestjs-catalog/client`, which the server validates against too.
38
+ * A fourth strategy added there fails to compile here until somebody writes the
39
+ * copy for it, which is the failure worth having: the alternative is a dropdown
40
+ * that quietly does not offer a strategy the server accepts.
41
+ */
42
+ const STRATEGY_COPY = {
43
+ accepted: {
44
+ label: 'Accepted — nothing reconciles them',
45
+ hint: 'An append-only ledger, or a dataset where a few stale rows cost less than a nightly full read.',
46
+ },
47
+ 'soft-deleted-at-source': {
48
+ label: 'Soft-deleted at the source',
49
+ hint: 'The source flips a column instead of removing the row, so the watermark sees the deletion as an ordinary change.',
50
+ },
51
+ 'periodic-full-reload': {
52
+ label: 'Periodic full reload',
53
+ hint: 'Full loads reconcile. Once the newest full load is older than the interval, incremental loads stop committing.',
54
+ },
55
+ };
56
+ /** The three, in the order the client package lists them, as a select understands them. */
57
+ export const DELETE_STRATEGIES = DELETE_RECONCILIATION_STRATEGIES.map((value) => ({
58
+ value,
59
+ ...STRATEGY_COPY[value],
60
+ }));
61
+ /**
62
+ * A select hands back a string. Narrow it rather than promise it is a strategy.
63
+ *
64
+ * The empty string is a real answer and not a failure: a type may legitimately
65
+ * have no delete strategy chosen yet, and that is the state this section exists
66
+ * to make visible. Defaulting an unknown value to one of the three would invent
67
+ * a decision nobody made — which is the one thing this whole mechanism is for.
68
+ */
69
+ function toDeleteStrategy(value) {
70
+ return isDeleteReconciliationStrategy(value) ? value : '';
71
+ }
72
+ /** How each layer should be described to somebody deciding whether they may edit. */
73
+ const SOURCE_LABEL = {
74
+ host: 'Fixed in code by this deployment',
75
+ stored: 'Set here, by an operator',
76
+ default: "The host's house-wide default",
77
+ none: 'Nothing declares it',
78
+ };
79
+ /** A blank field means "say nothing about this", which is not the same as zero. */
80
+ function numberOrNull(raw) {
81
+ const trimmed = raw.trim();
82
+ if (trimmed === '')
83
+ return null;
84
+ const value = Number(trimmed);
85
+ return Number.isFinite(value) ? value : null;
86
+ }
87
+ function text(value) {
88
+ return value === undefined ? '' : String(value);
89
+ }
90
+ /**
91
+ * What the form starts as.
92
+ *
93
+ * The STORED row, except where the host has locked a field — there the resolved
94
+ * value is shown instead, because the control is disabled and what a disabled
95
+ * control must show is the value actually in force. Filling the form with the
96
+ * host's values where it has NOT locked them would be worse than useless: it
97
+ * would turn "the house default applies" into "this type stores this", the
98
+ * first time anybody pressed save.
99
+ */
100
+ function draftFrom(view) {
101
+ const deletes = view.hostLocked.deletes ? view.resolved.deletes : view.stored?.deletes;
102
+ const rowCount = view.hostLocked.rowCount ? view.resolved.rowCount : view.stored?.rowCount;
103
+ return {
104
+ strategy: deletes?.strategy ?? '',
105
+ because: deletes?.because ?? '',
106
+ column: deletes?.strategy === 'soft-deleted-at-source' ? (deletes.column ?? '') : '',
107
+ withinMs: deletes?.strategy === 'periodic-full-reload' ? String(deletes.withinMs) : '',
108
+ maxShrink: text(rowCount?.maxShrink),
109
+ maxGrowth: text(rowCount?.maxGrowth),
110
+ minRows: text(rowCount?.minRows),
111
+ };
112
+ }
113
+ /**
114
+ * Everything wrong with the draft, by field.
115
+ *
116
+ * A mirror of what the server refuses with a 400, and deliberately a mirror
117
+ * rather than the authority: the server's answer always wins. What this buys is
118
+ * that the refusal arrives beside the field that caused it while somebody is
119
+ * typing, instead of as a message about a request they have stopped thinking
120
+ * about.
121
+ *
122
+ * Locked fields are skipped, because they are not being sent.
123
+ */
124
+ function problemsWith(draft, hostLocked) {
125
+ return {
126
+ ...(hostLocked.deletes ? {} : deleteProblems(draft)),
127
+ ...(hostLocked.rowCount ? {} : rowCountProblems(draft)),
128
+ };
129
+ }
130
+ function deleteProblems(draft) {
131
+ if (draft.strategy === '')
132
+ return {};
133
+ const problems = {};
134
+ // Required for all three, including `accepted` — especially `accepted`, which
135
+ // is the one somebody would otherwise pick to make the refusal go away
136
+ // without deciding anything.
137
+ if (draft.because.trim() === '') {
138
+ problems.because = 'Required. Say why this is the right answer for this type.';
139
+ }
140
+ if (draft.strategy === 'periodic-full-reload') {
141
+ const withinMs = numberOrNull(draft.withinMs);
142
+ if (withinMs === null || withinMs <= 0) {
143
+ problems.withinMs = 'Required, and greater than zero: the interval is what makes this real.';
144
+ }
145
+ }
146
+ return problems;
147
+ }
148
+ /**
149
+ * A blank bound is always fine — it means "say nothing about this" — so every
150
+ * check here is conditional on somebody having typed something.
151
+ */
152
+ function rowCountProblems(draft) {
153
+ const problems = {};
154
+ const maxShrink = numberOrNull(draft.maxShrink);
155
+ if (draft.maxShrink.trim() !== '' && (maxShrink === null || maxShrink <= 0 || maxShrink > 1)) {
156
+ problems.maxShrink = 'A fraction above 0 and up to 1. 0.5 refuses a load that halves the type.';
157
+ }
158
+ const maxGrowth = numberOrNull(draft.maxGrowth);
159
+ if (draft.maxGrowth.trim() !== '' && (maxGrowth === null || maxGrowth <= 1)) {
160
+ problems.maxGrowth = 'A ratio above 1. Leave it blank to never refuse growth.';
161
+ }
162
+ const minRows = numberOrNull(draft.minRows);
163
+ if (draft.minRows.trim() !== '' && (minRows === null || minRows < 0)) {
164
+ problems.minRows = 'A row count, zero or more.';
165
+ }
166
+ return problems;
167
+ }
168
+ /** The row-count fields that carry a number, as the body wants them. */
169
+ function rowCountFrom(draft) {
170
+ const maxShrink = numberOrNull(draft.maxShrink);
171
+ const maxGrowth = numberOrNull(draft.maxGrowth);
172
+ const minRows = numberOrNull(draft.minRows);
173
+ if (maxShrink === null && maxGrowth === null && minRows === null)
174
+ return undefined;
175
+ return {
176
+ ...(maxShrink === null ? {} : { maxShrink }),
177
+ ...(maxGrowth === null ? {} : { maxGrowth }),
178
+ ...(minRows === null ? {} : { minRows }),
179
+ };
180
+ }
181
+ /** The chosen strategy as the union member it is, or nothing chosen. */
182
+ function deletesFrom(draft) {
183
+ const because = draft.because.trim();
184
+ if (draft.strategy === 'accepted')
185
+ return { strategy: 'accepted', because };
186
+ if (draft.strategy === 'soft-deleted-at-source') {
187
+ const column = draft.column.trim();
188
+ return { strategy: 'soft-deleted-at-source', because, ...(column ? { column } : {}) };
189
+ }
190
+ if (draft.strategy === 'periodic-full-reload') {
191
+ const withinMs = numberOrNull(draft.withinMs);
192
+ // Unreachable through the form — `problemsWith` disables the button first —
193
+ // and typed rather than asserted, so it stays unreachable if it moves.
194
+ if (withinMs === null)
195
+ return undefined;
196
+ return { strategy: 'periodic-full-reload', because, withinMs };
197
+ }
198
+ return undefined;
199
+ }
200
+ /**
201
+ * What the form would send.
202
+ *
203
+ * A locked field is OMITTED rather than sent unchanged. The server answers 409
204
+ * for a write to a field the host owns, and a body that echoed the host's value
205
+ * back would turn every save of the other half into that refusal.
206
+ */
207
+ function bodyFrom(draft, hostLocked) {
208
+ const deletes = hostLocked.deletes ? undefined : deletesFrom(draft);
209
+ const rowCount = hostLocked.rowCount ? undefined : rowCountFrom(draft);
210
+ return {
211
+ ...(deletes ? { deletes } : {}),
212
+ ...(rowCount ? { rowCount } : {}),
213
+ };
214
+ }
215
+ /** Milliseconds, in the unit a person would have said it in. */
216
+ function describeInterval(ms) {
217
+ if (!Number.isFinite(ms) || ms <= 0)
218
+ return `${ms} ms`;
219
+ const trim = (value) => String(Math.round(value * 10) / 10);
220
+ const hours = ms / 3_600_000;
221
+ if (hours >= 48)
222
+ return `${trim(hours / 24)} days`;
223
+ if (hours >= 1)
224
+ return `${trim(hours)} hours`;
225
+ return `${trim(ms / 60_000)} minutes`;
226
+ }
227
+ export function LoadExpectationSection({ typeName, displayName }) {
228
+ const client = useCatalogClient();
229
+ const { data: view, isPending, isError, error, } = useQuery({
230
+ queryKey: catalogQueryKeys.loadExpectation(typeName),
231
+ queryFn: () => client.loadExpectation(typeName),
232
+ // Not retried. The likely failure is a host that serves no pipeline
233
+ // endpoints at all, and four attempts at a 404 over thirty seconds is a
234
+ // section that says nothing for half a minute before saying that.
235
+ retry: false,
236
+ });
237
+ return (_jsxs("section", { className: "mt-10", children: [_jsxs("div", { className: "mb-3", children: [_jsx("h2", { className: cn('font-mono text-[11px] uppercase tracking-[0.16em]', MUTED), children: "Load expectation" }), _jsx("p", { className: cn('mt-1 text-xs', MUTED), children: "How this type reconciles rows deleted at the source, and how far one load may move its row count. Checked before a load is allowed to become the data everybody reads." })] }), isPending && _jsx("p", { className: cn('font-mono text-xs', MUTED), children: "Reading the expectation\u2026" }), isError && (_jsxs("div", { className: cn('rounded-lg border px-4 py-3', RULE, PANEL), children: [_jsx("p", { className: "text-sm", children: "Could not read the load expectation." }), _jsxs("p", { className: cn('mt-1 text-xs', SECONDARY), children: ["It is served by the pipeline endpoints, which are the host's rather than this library's \u2014 this deployment may not mount them, or this account may not read them. Nothing here says whether a load of ", displayName, " would be refused."] }), error instanceof Error && (_jsx("p", { className: cn('mt-1 font-mono text-[11px]', MUTED), children: error.message }))] })), view && _jsx(LoadExpectationBody, { view: view, displayName: displayName })] }));
238
+ }
239
+ function LoadExpectationBody({ view, displayName, }) {
240
+ const deletes = view.resolved.deletes;
241
+ return (_jsxs("div", { className: "space-y-4", children: [view.deletesFrom === 'none' ? (
242
+ // The whole reason somebody opens this section. Said in words, and
243
+ // said first: a blank strategy field is read as "not filled in yet",
244
+ // which is exactly the wrong conclusion — the load is already refused.
245
+ _jsxs("div", { className: cn('rounded-lg border border-amber-300 bg-amber-50 px-4 py-3', 'dark:border-amber-900 dark:bg-amber-950/40'), children: [_jsxs("p", { className: "text-sm text-amber-900 dark:text-amber-200", children: ["Nothing declares how ", displayName, " reconciles deletes, so an incremental load of it will be refused."] }), _jsx("p", { className: "mt-1 text-xs text-amber-800 dark:text-amber-300/80", children: "A full load still commits \u2014 it replaces the whole type, so deletions reconcile by construction. What is blocked is the incremental path, until somebody chooses a strategy below and writes down why." })] })) : (_jsxs("div", { className: cn('rounded-lg border px-4 py-3', RULE, PANEL), children: [_jsxs("div", { className: "flex flex-wrap items-baseline justify-between gap-2", children: [_jsxs("p", { className: "text-sm", children: ["Deletes: ", _jsx("span", { className: "font-mono", children: deletes?.strategy }), deletes?.strategy === 'periodic-full-reload' && (_jsxs("span", { className: SECONDARY, children: [' ', "\u00B7 reconciled every ", describeInterval(deletes.withinMs)] })), deletes?.strategy === 'soft-deleted-at-source' && deletes.column && (_jsxs("span", { className: SECONDARY, children: [" \u00B7 column ", deletes.column] }))] }), _jsx(SourceBadge, { source: view.deletesFrom })] }), deletes && (
246
+ // Prose, and marked up as prose: this is a sentence somebody is
247
+ // accountable for, not a config value. In the table below it would
248
+ // be skimmed like one.
249
+ _jsxs("blockquote", { className: "mt-2 border-l-2 border-sky-200 pl-4 dark:border-sky-900", children: [_jsx("p", { className: "text-sm leading-relaxed", children: deletes.because }), _jsx(Attribution, { view: view })] }))] })), _jsx(ProvenanceTable, { view: view }), _jsx(ExpectationForm, { view: view, displayName: displayName })] }));
250
+ }
251
+ /**
252
+ * Who wrote the sentence above, and when.
253
+ *
254
+ * Rendered from the STORED row only. A `because` that came from the host was
255
+ * written in a commit, and naming the person the server happens to be running
256
+ * as would attribute it to somebody who never saw it.
257
+ */
258
+ function Attribution({ view }) {
259
+ const stored = view.stored;
260
+ if (!stored) {
261
+ return (_jsx("p", { className: cn('mt-1.5 text-[11px]', MUTED), children: "Declared in this deployment's code. Its author is in the commit that set it, not here." }));
262
+ }
263
+ const who = stored.setByActor ? `${stored.setByActor}, through ${stored.setBy}` : stored.setBy;
264
+ return (_jsxs("p", { className: cn('mt-1.5 text-[11px]', MUTED), children: ["Set by ", who, " on ", new Date(stored.setAt).toLocaleString(), view.hostLocked.deletes && ' — and overridden since, by what the host declares in code.'] }));
265
+ }
266
+ function SourceBadge({ source }) {
267
+ return (_jsxs("span", { className: cn('flex items-center gap-1 rounded-sm bg-zinc-100 px-1.5 py-0.5 text-[10px] dark:bg-zinc-800', SECONDARY), children: [source === 'host' && _jsx(Lock, { size: 10, "aria-hidden": true }), SOURCE_LABEL[source]] }));
268
+ }
269
+ /**
270
+ * Which layer won each field.
271
+ *
272
+ * Field by field rather than one badge for the whole expectation, because the
273
+ * resolution IS field by field — a host that pinned a row-count bound and said
274
+ * nothing about deletes leaves this type with two different answers to "may I
275
+ * change this", and one badge would have to pick one of them and be wrong about
276
+ * the other.
277
+ */
278
+ function ProvenanceTable({ view }) {
279
+ const rows = useMemo(() => {
280
+ const bound = view.resolved.rowCount;
281
+ return [
282
+ {
283
+ id: 'deletes',
284
+ field: 'Delete reconciliation',
285
+ value: view.resolved.deletes?.strategy ?? 'not declared',
286
+ source: view.deletesFrom,
287
+ },
288
+ {
289
+ id: 'maxShrink',
290
+ field: 'Max shrink',
291
+ value: bound?.maxShrink === undefined
292
+ ? 'not declared'
293
+ : `${bound.maxShrink} of the served snapshot`,
294
+ source: view.rowCountFrom,
295
+ },
296
+ {
297
+ id: 'maxGrowth',
298
+ field: 'Max growth',
299
+ // "never refused" rather than a dash: absent is the documented
300
+ // behaviour here, not a missing value somebody forgot to fill in.
301
+ value: bound?.maxGrowth === undefined ? 'growth is never refused' : `${bound.maxGrowth}×`,
302
+ source: view.rowCountFrom,
303
+ },
304
+ {
305
+ id: 'minRows',
306
+ field: 'Min rows for a ratio',
307
+ value: bound?.minRows === undefined ? 'not declared' : `${bound.minRows} rows`,
308
+ source: view.rowCountFrom,
309
+ },
310
+ ];
311
+ }, [view]);
312
+ const columns = useMemo(() => [
313
+ {
314
+ id: 'field',
315
+ header: 'Field',
316
+ accessorFn: (row) => row.field,
317
+ cell: ({ row }) => (_jsx("span", { className: "text-xs", children: row.original.field })),
318
+ },
319
+ {
320
+ id: 'value',
321
+ header: 'In force',
322
+ accessorFn: (row) => row.value,
323
+ cell: ({ row }) => (_jsx("span", { className: cn('font-mono text-[11px]', SECONDARY), children: row.original.value })),
324
+ },
325
+ {
326
+ id: 'source',
327
+ header: 'Where it came from',
328
+ accessorFn: (row) => row.source,
329
+ cell: ({ row }) => (_jsx(SourceBadge, { source: row.original.source })),
330
+ },
331
+ ], []);
332
+ return (_jsx("div", { className: cn('overflow-hidden rounded-lg border', RULE, PANEL), children: _jsx(DataTable, { data: rows, columns: columns, getRowId: (row) => row.id, columnClassName: (id) => (id === 'source' ? 'w-[34%]' : 'w-[33%]') }) }));
333
+ }
334
+ /**
335
+ * The editor.
336
+ *
337
+ * A locked field is shown and disabled rather than hidden, which is the rule
338
+ * this section is built around: hiding it would leave a screen that cannot
339
+ * explain why the type behaves the way it does, and leaving it enabled would
340
+ * offer an edit the server answers 409 to — an edit that silently fails is the
341
+ * one outcome worse than either.
342
+ */
343
+ function ExpectationForm({ view, displayName, }) {
344
+ const client = useCatalogClient();
345
+ const queryClient = useQueryClient();
346
+ const [draft, setDraft] = useState(() => draftFrom(view));
347
+ const update = (patch) => setDraft({ ...draft, ...patch });
348
+ const invalidate = () => queryClient.invalidateQueries({
349
+ queryKey: catalogQueryKeys.loadExpectation(view.typeName),
350
+ });
351
+ const save = useMutation({
352
+ mutationFn: () => client.setLoadExpectation(view.typeName, bodyFrom(draft, view.hostLocked)),
353
+ // Refetched rather than written from the answer: what belongs on screen is
354
+ // the RESOLVED expectation, and resolving it against what the host declared
355
+ // is the server's job. See `CatalogClient.setLoadExpectation`.
356
+ onSuccess: invalidate,
357
+ });
358
+ const clear = useMutation({
359
+ mutationFn: () => client.clearLoadExpectation(view.typeName),
360
+ onSuccess: invalidate,
361
+ });
362
+ const problems = problemsWith(draft, view.hostLocked);
363
+ const body = bodyFrom(draft, view.hostLocked);
364
+ const nothingToSave = body.deletes === undefined && body.rowCount === undefined;
365
+ const everythingLocked = view.hostLocked.deletes && view.hostLocked.rowCount;
366
+ const blocked = Object.keys(problems).length > 0 || nothingToSave || everythingLocked;
367
+ return (_jsxs("form", { className: cn('space-y-4 rounded-lg border p-4', RULE, PANEL), onSubmit: (event) => {
368
+ event.preventDefault();
369
+ // Checked here as well as on the button. A disabled button is a
370
+ // statement about the pointer; a form still submits on Enter, and a
371
+ // `because` this screen let through would be stored as an empty
372
+ // sentence nobody can be held to.
373
+ if (blocked || save.isPending)
374
+ return;
375
+ save.mutate();
376
+ }, children: [_jsxs("p", { className: cn('font-mono text-[10px] uppercase tracking-[0.14em]', MUTED), children: ["Set it for ", displayName] }), _jsx(DeleteFields, { draft: draft, update: update, problems: problems, view: view }), _jsx(RowCountFields, { draft: draft, update: update, problems: problems, view: view }), _jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsx(Button, { type: "submit", size: "sm", disabled: blocked || save.isPending, children: save.isPending ? 'Saving…' : 'Save expectation' }), view.stored && (_jsx(Button, { size: "sm", variant: "outline", disabled: clear.isPending, onClick: () => clear.mutate(), children: clear.isPending ? 'Clearing…' : 'Clear the stored one' })), everythingLocked && (_jsx("span", { className: cn('text-[11px]', SECONDARY), children: "Every field here is fixed in code, so there is nothing this screen can store." }))] }), save.error && (_jsx("p", { className: cn('text-[11px]', DANGER), children: save.error instanceof Error ? save.error.message : 'Could not save.' })), clear.error && (_jsx("p", { className: cn('text-[11px]', DANGER), children: clear.error instanceof Error ? clear.error.message : 'Could not clear it.' }))] }));
377
+ }
378
+ /** A hint, or the reason the field is refused, in its place. */
379
+ function hintFor(problem, otherwise) {
380
+ return problem ? _jsx("span", { className: DANGER, children: problem }) : otherwise;
381
+ }
382
+ /**
383
+ * The strategy, its reason, and whichever one extra field the strategy needs.
384
+ *
385
+ * The extra field is rendered per strategy rather than always: an interval box
386
+ * beside `accepted` is a field that does nothing, and a form full of those is
387
+ * how somebody comes to believe a value they typed is in force.
388
+ */
389
+ function DeleteFields({ draft, update, problems, view }) {
390
+ const locked = view.hostLocked.deletes;
391
+ return (_jsxs(_Fragment, { children: [locked && (_jsxs("p", { className: cn('text-[11px]', SECONDARY), children: ["This deployment fixed the delete strategy in code, in its", _jsx("span", { className: "font-mono", children: " CATALOG_LOAD_EXPECTATIONS" }), ". It is shown here and cannot be changed from this screen \u2014 a write would be refused."] })), _jsxs("div", { className: "grid gap-3 sm:grid-cols-2", children: [_jsx(SelectField, { label: "Deletes", ariaLabel: "Delete reconciliation strategy", value: draft.strategy, onValueChange: (value) => update({ strategy: toDeleteStrategy(value) }), options: [...DELETE_STRATEGIES], placeholder: "Nothing chosen \u2014 incremental loads refused", disabled: locked }), draft.strategy === 'periodic-full-reload' && (_jsx(TextField, { label: "Reconcile within (ms)", value: draft.withinMs, onChange: (withinMs) => update({ withinMs }), inputMode: "numeric", placeholder: "86400000", disabled: locked, hint: hintFor(problems.withinMs, 'Once the newest full load is older than this, incremental loads stop committing.') })), draft.strategy === 'soft-deleted-at-source' && (_jsx(TextField, { label: "Column (optional)", value: draft.column, onChange: (column) => update({ column }), placeholder: "deleted_at", disabled: locked, hint: "Which column the source flips. Recorded for the next reader; nothing here verifies it." }))] }), _jsx(TextAreaField, { label: "Because", value: draft.because, onChange: (because) => update({ because }), rows: 3, placeholder: "Why this is the right answer for this type.", disabled: locked, hint: hintFor(problems.because, 'Required for every strategy. It is signed with your name and shown to whoever reads this next.') })] }));
392
+ }
393
+ /** The three bounds. All optional, and a blank one says nothing rather than zero. */
394
+ function RowCountFields({ draft, update, problems, view }) {
395
+ const locked = view.hostLocked.rowCount;
396
+ return (_jsxs(_Fragment, { children: [locked && (_jsx("p", { className: cn('text-[11px]', SECONDARY), children: "This deployment fixed the row-count bounds in code. They are shown here and cannot be changed from this screen." })), _jsxs("div", { className: "grid gap-3 sm:grid-cols-3", children: [_jsx(TextField, { label: "Max shrink", value: draft.maxShrink, onChange: (maxShrink) => update({ maxShrink }), inputMode: "numeric", placeholder: "0.5", disabled: locked, hint: hintFor(problems.maxShrink, 'The most of the served snapshot one load may lose.') }), _jsx(TextField, { label: "Max growth", value: draft.maxGrowth, onChange: (maxGrowth) => update({ maxGrowth }), inputMode: "numeric", placeholder: "blank \u2014 never refused", disabled: locked, hint: hintFor(problems.maxGrowth, 'A backfill is usually a good day. Leave it blank unless it is not.') }), _jsx(TextField, { label: "Min rows", value: draft.minRows, onChange: (minRows) => update({ minRows }), inputMode: "numeric", placeholder: "100", disabled: locked, hint: hintFor(problems.minRows, 'Below this, no ratio applies — a percentage of a small number is noise.') })] })] }));
397
+ }
package/dist/context.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { CatalogAuditEvent, CatalogConnection, CatalogConnector, CatalogObjectPage, CatalogQueryRelation, CatalogQueryResult, CatalogRevision, CatalogSearchResult, CatalogSnapshot, CatalogTraceList, CatalogTransform, ConnectionCheck, ConnectorRun, Dashboard, DashboardCard, ObjectQueryParams, PropertyPatch, SaveQueryInput, SavedQuery, TraceQuery, TransformLanguage, TransformResult, TypePatch } from '@dudousxd/nestjs-catalog/client';
1
+ import type { CatalogAuditEvent, CatalogConnection, CatalogConnector, CatalogObjectPage, CatalogQueryRelation, CatalogQueryResult, CatalogRevision, CatalogSearchResult, CatalogSnapshot, CatalogTraceList, CatalogTransform, ConnectionCheck, ConnectorRun, Dashboard, DashboardCard, DeleteReconciliation, LoadExpectation, LoadExpectationInput, ObjectQueryParams, PropertyPatch, ResolvedLoadExpectation, RowCountBound, SaveQueryInput, SavedQuery, StoredLoadExpectation, TraceQuery, TransformLanguage, TransformResult, TypePatch } from '@dudousxd/nestjs-catalog/client';
2
2
  import { type ReactNode } from 'react';
3
3
  import type { EmbeddedChartPayload, EmbeddedDashboardPayload } from './embed/payload';
4
4
  import { type PeopleQuery } from './routes';
@@ -77,6 +77,28 @@ export interface PipelineCapabilities {
77
77
  */
78
78
  durable?: WorkflowDurability;
79
79
  }
80
+ /**
81
+ * What a load has to be true of before it becomes the data everybody reads.
82
+ *
83
+ * RE-EXPORTED rather than mirrored, and the distinction is the same one
84
+ * {@link CatalogRevision} above turns on: {@link PipelineCapabilities} is
85
+ * mirrored because naming it would mean importing
86
+ * `@dudousxd/nestjs-catalog-pipeline`, a package built for a Node process with
87
+ * database drivers behind optional imports. These shapes have no such problem —
88
+ * they are plain declarations on `@dudousxd/nestjs-catalog/client`, the entry
89
+ * point that exists precisely so a browser can name the catalog's own
90
+ * contracts, and a second copy here is what would drift.
91
+ *
92
+ * Named from this module at all, rather than left for a host to import from the
93
+ * other package, for the reason the whole of this file is: everything else this
94
+ * client returns is reachable from here, and typing a variable should not
95
+ * require knowing which of the two packages declares which shape.
96
+ *
97
+ * The enforcement functions are deliberately NOT reachable from a browser.
98
+ * They decide whether a load commits, they live in the pipeline package, and a
99
+ * console running its own copy would be a second answer to a question with one.
100
+ */
101
+ export type { DeleteReconciliation, LoadExpectation, LoadExpectationInput, ResolvedLoadExpectation, RowCountBound, StoredLoadExpectation, };
80
102
  /**
81
103
  * What a caller may set on a connection.
82
104
  *
@@ -409,6 +431,31 @@ export interface CatalogClient {
409
431
  */
410
432
  publishType(name: string, schema: unknown): Promise<unknown>;
411
433
  listRuns(connectorId?: string): Promise<ConnectorRun[]>;
434
+ /**
435
+ * What one type promises about deletes and row counts, resolved.
436
+ *
437
+ * Per type and never per connector: the three ways rows arrive — a
438
+ * connector, a workflow sink, an application POSTing to the publish API —
439
+ * end at the same two publish methods, so a per-connector answer would cover
440
+ * one of the three and leave one dataset with two answers to one question.
441
+ */
442
+ loadExpectation(typeName: string): Promise<ResolvedLoadExpectation>;
443
+ /**
444
+ * Store one, or replace what is stored.
445
+ *
446
+ * The answer is typed `unknown` and callers are expected to refetch. That is
447
+ * not laziness: what a screen has to show is the RESOLVED expectation, which
448
+ * is a merge of this write with whatever the host declared in code, and the
449
+ * merge is the server's to perform. A screen that wrote this response into
450
+ * its cache would be claiming the stored row is the one in force, which is
451
+ * exactly what {@link ResolvedLoadExpectation.hostLocked} exists to deny.
452
+ *
453
+ * Refuses by name when the transport cannot `PUT`, rather than resolving
454
+ * having done nothing — see {@link CatalogTransport.put}.
455
+ */
456
+ setLoadExpectation(typeName: string, input: LoadExpectationInput): Promise<unknown>;
457
+ /** Drop the stored row. Anything the host declared in code survives it. */
458
+ clearLoadExpectation(typeName: string): Promise<unknown>;
412
459
  listTransforms(): Promise<CatalogTransform[]>;
413
460
  saveTransform(input: TransformInput): Promise<CatalogTransform>;
414
461
  deleteTransform(id: string): Promise<{
@@ -535,6 +582,16 @@ export declare const catalogQueryKeys: {
535
582
  */
536
583
  transformRevisions: (id: string) => readonly ["nestjs-catalog", "pipeline", "transforms", string, "revisions"];
537
584
  runs: (connectorId?: string) => readonly ["nestjs-catalog", "pipeline", "runs", string];
585
+ /**
586
+ * One type's resolved load expectation.
587
+ *
588
+ * Under the `pipeline` prefix rather than beside `snapshot`, even though the
589
+ * screen that reads it is the Model screen: the endpoint is served by the
590
+ * host's pipeline controller, not by the catalog library, so a host
591
+ * invalidating "everything the pipeline knows" has to reach this too. Keyed
592
+ * per type because that is the grain of the answer.
593
+ */
594
+ loadExpectation: (typeName: string) => readonly ["nestjs-catalog", "pipeline", "expectations", string];
538
595
  workflows: readonly ["nestjs-catalog", "pipeline", "workflows"];
539
596
  /**
540
597
  * The embed keys, under one prefix so a host can invalidate every embedded
package/dist/context.js CHANGED
@@ -74,6 +74,16 @@ export function CatalogProvider({ transport, pipelineBasePath = DEFAULT_PIPELINE
74
74
  // run" into "runs of the connector whose id is the empty string", which
75
75
  // is an empty list that looks like a system that has never run anything.
76
76
  listRuns: (connectorId) => transport.get(pipeline.runs(), connectorId ? { connector: connectorId } : undefined),
77
+ loadExpectation: (typeName) => transport.get(pipeline.loadExpectation(typeName)),
78
+ setLoadExpectation: (typeName, input) => {
79
+ if (!transport.put) {
80
+ throw new Error('This transport cannot PUT, so it cannot store a load expectation. Implement `put` ' +
81
+ 'on the transport you passed to CatalogProvider — storing one is an idempotent ' +
82
+ 'upsert of the whole per-type row, which is why the route is a PUT and not a POST.');
83
+ }
84
+ return transport.put(pipeline.loadExpectation(typeName), input);
85
+ },
86
+ clearLoadExpectation: (typeName) => transport.delete(pipeline.loadExpectation(typeName)),
77
87
  listTransforms: () => transport.get(pipeline.transforms()),
78
88
  saveTransform: (input) => transport.post(pipeline.transforms(), input),
79
89
  deleteTransform: (id) => transport.delete(pipeline.transform(id)),
@@ -138,6 +148,16 @@ export const catalogQueryKeys = {
138
148
  */
139
149
  transformRevisions: (id) => ['nestjs-catalog', 'pipeline', 'transforms', id, 'revisions'],
140
150
  runs: (connectorId) => ['nestjs-catalog', 'pipeline', 'runs', connectorId ?? 'all'],
151
+ /**
152
+ * One type's resolved load expectation.
153
+ *
154
+ * Under the `pipeline` prefix rather than beside `snapshot`, even though the
155
+ * screen that reads it is the Model screen: the endpoint is served by the
156
+ * host's pipeline controller, not by the catalog library, so a host
157
+ * invalidating "everything the pipeline knows" has to reach this too. Keyed
158
+ * per type because that is the grain of the answer.
159
+ */
160
+ loadExpectation: (typeName) => ['nestjs-catalog', 'pipeline', 'expectations', typeName],
141
161
  workflows: ['nestjs-catalog', 'pipeline', 'workflows'],
142
162
  /**
143
163
  * The embed keys, under one prefix so a host can invalidate every embedded
package/dist/index.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  export { CatalogManager, type CatalogManagerProps } from './CatalogManager';
2
2
  export { CoverageLedger } from './CoverageLedger';
3
3
  export { EditableField } from './EditableField';
4
+ export { DELETE_STRATEGIES, LoadExpectationSection, type LoadExpectationSectionProps, } from './LoadExpectationSection';
4
5
  export { cn } from './cn';
5
6
  export { ObjectExplorer, type ObjectExplorerProps } from './ObjectExplorer';
6
7
  export { DashboardBoard } from './DashboardBoard';
@@ -23,7 +24,7 @@ export { AccessConsole, type AccessConsoleProps } from './AccessConsole';
23
24
  export { type CatalogWorkflow, describeDurability, type DurabilityCopy, isWorkflowNodeKind, newLocalId, nodeName, producedTypes, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, type WorkflowDurability, type WorkflowEdge, type WorkflowGraph, type WorkflowInput, type WorkflowNode, type WorkflowNodeKind, type WorkflowRun, type WorkflowRunNode, type WorkflowSinkNode, type WorkflowSourceNode, type WorkflowTransformNode, } from './workflow/model';
24
25
  export { WORKFLOW_NAME } from './workflow/name';
25
26
  export { canConnect, type ConnectionVerdict, edgeId, hasBlockingProblem, problemsByNode, type ValidateOptions, validateWorkflow, type WorkflowDraft, type WorkflowProblem, type WorkflowProblemCode, type WorkflowProblemLevel, wouldCycle, } from './workflow/validate';
26
- export { type CatalogClient, type CatalogIdentity, type CatalogRevision, type CatalogPeoplePage, type CatalogPersonRole, type CatalogPersonSummary, type CatalogPrincipalSummary, CatalogProvider, type CatalogProviderProps, type CatalogTransport, type ConnectionInput, type ConnectorInput, catalogQueryKeys, type PersonInput, type PersonUpsertResult, type PipelineCapabilities, type TransformInput, useCatalogClient, } from './context';
27
+ export { type CatalogClient, type CatalogIdentity, type CatalogRevision, type CatalogPeoplePage, type CatalogPersonRole, type CatalogPersonSummary, type CatalogPrincipalSummary, CatalogProvider, type CatalogProviderProps, type CatalogTransport, type ConnectionInput, type ConnectorInput, catalogQueryKeys, type DeleteReconciliation, type LoadExpectation, type LoadExpectationInput, type ResolvedLoadExpectation, type RowCountBound, type StoredLoadExpectation, type PersonInput, type PersonUpsertResult, type PipelineCapabilities, type TransformInput, useCatalogClient, } from './context';
27
28
  export { type AccessRoutes, accessRoutes, DEFAULT_ACCESS_BASE_PATH, DEFAULT_PIPELINE_BASE_PATH, DEFAULT_PUBLISH_BASE_PATH, embedRoutes, type PeopleQuery, type PipelineRoutes, pipelineRoutes, } from './routes';
28
29
  export { ConfirmDialog } from './ui/dialog';
29
30
  export { FieldGroup, TextAreaField, TextField } from './ui/field';
package/dist/index.js CHANGED
@@ -1,6 +1,10 @@
1
1
  export { CatalogManager } from './CatalogManager';
2
2
  export { CoverageLedger } from './CoverageLedger';
3
3
  export { EditableField } from './EditableField';
4
+ // Mounted on the Model screen already. Exported because a host that builds its
5
+ // own type panel out of this package's parts should not have to rebuild the one
6
+ // section that can say an incremental load of a type is currently refused.
7
+ export { DELETE_STRATEGIES, LoadExpectationSection, } from './LoadExpectationSection';
4
8
  export { cn } from './cn';
5
9
  export { ObjectExplorer } from './ObjectExplorer';
6
10
  export { DashboardBoard } from './DashboardBoard';
package/dist/routes.d.ts CHANGED
@@ -2,22 +2,35 @@
2
2
  * The paths behind the pipeline and access screens — and, for now, the embed
3
3
  * components, which are the documented exception at the top of the file.
4
4
  *
5
- * These deliberately do **not** live in `@dudousxd/nestjs-catalog/client` beside
6
- * `catalogRoutes`, and the difference is worth being precise about, because it
7
- * is the difference between a route builder that is a promise and one that is a
8
- * guess.
5
+ * Most of these deliberately do **not** live in
6
+ * `@dudousxd/nestjs-catalog/client` beside `catalogRoutes`, and the difference
7
+ * is worth being precise about, because it is the difference between a route
8
+ * builder that is a promise and one that is a default.
9
9
  *
10
- * `catalogRoutes` describes paths the catalog library's own controller serves.
11
- * Install the library, register the module, and `/catalog/objects/...` exists —
12
- * the builder is the library documenting itself, and it cannot be wrong.
10
+ * `catalogRoutes` is a frozen object of builders that take no base path: the
11
+ * paths the catalog library's own controller serves, at the segment it serves
12
+ * them under. Install the library, register the module, and
13
+ * `/catalog/objects/...` exists — the builder is the library documenting itself.
13
14
  *
14
- * Connectors, transforms and access are the other shape. The library defines
15
- * their *model* — `CatalogPipelineStore`, `CatalogConnection`, `CatalogPrincipal`
16
- * — but ships no controller for any of them, because how a deployment exposes
17
- * the code that reshapes its data, and who may create an account, are decisions
18
- * that belong to the deployment. Putting `pipelineRoutes` next to `catalogRoutes`
19
- * would tell a reader that installing the library makes `/pipeline/connectors`
20
- * answer, and it does not: they would get a 404 with nothing to point at.
15
+ * Connectors, transforms and access are the other shape, and what makes them so
16
+ * is not that nothing serves them. It is that WHERE they are served is the
17
+ * host's decision, which a frozen builder cannot express:
18
+ *
19
+ * - Connectors, transforms, workflows and runs are served by
20
+ * `createPipelineController`, which ships in
21
+ * `@dudousxd/nestjs-catalog-pipeline` — a *separate* package, mounted under
22
+ * whatever `path` its `forRoot` was given, and mounted nowhere at all if it
23
+ * was given none. Installing `@dudousxd/nestjs-catalog` does not make
24
+ * `/pipeline/connectors` answer, so putting `pipelineRoutes` beside
25
+ * `catalogRoutes` would tell a reader it does, and they would get a 404 with
26
+ * nothing to point at.
27
+ * - Access is the one that used to be described here as having no controller
28
+ * either, and it does have one: `createAccessController` is in the catalog
29
+ * library and `CatalogModule.forRoot` mounts it unless the host passes
30
+ * `controller: false`. What it does not have is a fixed path — it mounts
31
+ * under `accessPath`, a sibling of the catalog's own mount point — so it is
32
+ * still a default rather than a promise, for the second reason rather than
33
+ * the first.
21
34
  *
22
35
  * So the builders live here, in the package that ships the screens that need
23
36
  * them, and are stated as a *default* the host can move. The defaults are
@@ -25,6 +38,19 @@
25
38
  * `/api/pipeline` — because the transport is what knows the API prefix, and a
26
39
  * screen that hardcoded one app's mount point would be unusable in the next app.
27
40
  *
41
+ * The two load-expectation paths are the case that says what the rule above
42
+ * really is. They are served by that same pipeline controller in that same
43
+ * separate package, yet their builder — `pipelineExpectationRoutes` — is in
44
+ * `@dudousxd/nestjs-catalog/client`, and `pipelineRoutes` below borrows it
45
+ * instead of writing the strings again. That is not an exception, because the
46
+ * test was never which package a builder lives in: it is whether the builder
47
+ * takes a base path. `pipelineExpectationRoutes` does, so it promises nothing
48
+ * about where the routes are mounted no matter where it sits. It sits there
49
+ * because the wire types it goes with — `LoadExpectationInput`,
50
+ * `ResolvedLoadExpectation` — are declared in that entry point and the pipeline
51
+ * controller reads them from there too, and a path split from the shapes it
52
+ * returns is how the two halves of one contract come to be moved separately.
53
+ *
28
54
  * What this package therefore asks of a host is an HTTP surface with these
29
55
  * shapes, wherever it wants to mount it. That contract is the response types on
30
56
  * `CatalogClient` plus these paths, and a host that would rather satisfy it from
@@ -121,6 +147,25 @@ export interface PipelineRoutes {
121
147
  workflows(): string;
122
148
  workflow(id: string): string;
123
149
  runWorkflow(id: string): string;
150
+ /**
151
+ * Every per-type load expectation an operator has stored.
152
+ *
153
+ * Keyed by object type and nothing else. A connector, a workflow sink and an
154
+ * application POSTing to the publish API all end at the same publish methods
155
+ * and all have the same delete problem, so a per-connector route would have
156
+ * given one dataset two answers to one question.
157
+ */
158
+ loadExpectations(): string;
159
+ /**
160
+ * One type's expectation. GET resolves it and says where each field came
161
+ * from; PUT stores one; DELETE drops the stored row and leaves the host's.
162
+ *
163
+ * The GET answers a merge rather than the stored row, because the stored row
164
+ * alone cannot tell a screen whether it is the one in force — a host that
165
+ * declared the same type in code wins, and a screen that showed the stored
166
+ * value would offer an edit that is refused.
167
+ */
168
+ loadExpectation(typeName: string): string;
124
169
  }
125
170
  export declare function pipelineRoutes(basePath?: string): PipelineRoutes;
126
171
  export interface AccessRoutes {
package/dist/routes.js CHANGED
@@ -2,22 +2,35 @@
2
2
  * The paths behind the pipeline and access screens — and, for now, the embed
3
3
  * components, which are the documented exception at the top of the file.
4
4
  *
5
- * These deliberately do **not** live in `@dudousxd/nestjs-catalog/client` beside
6
- * `catalogRoutes`, and the difference is worth being precise about, because it
7
- * is the difference between a route builder that is a promise and one that is a
8
- * guess.
5
+ * Most of these deliberately do **not** live in
6
+ * `@dudousxd/nestjs-catalog/client` beside `catalogRoutes`, and the difference
7
+ * is worth being precise about, because it is the difference between a route
8
+ * builder that is a promise and one that is a default.
9
9
  *
10
- * `catalogRoutes` describes paths the catalog library's own controller serves.
11
- * Install the library, register the module, and `/catalog/objects/...` exists —
12
- * the builder is the library documenting itself, and it cannot be wrong.
10
+ * `catalogRoutes` is a frozen object of builders that take no base path: the
11
+ * paths the catalog library's own controller serves, at the segment it serves
12
+ * them under. Install the library, register the module, and
13
+ * `/catalog/objects/...` exists — the builder is the library documenting itself.
13
14
  *
14
- * Connectors, transforms and access are the other shape. The library defines
15
- * their *model* — `CatalogPipelineStore`, `CatalogConnection`, `CatalogPrincipal`
16
- * — but ships no controller for any of them, because how a deployment exposes
17
- * the code that reshapes its data, and who may create an account, are decisions
18
- * that belong to the deployment. Putting `pipelineRoutes` next to `catalogRoutes`
19
- * would tell a reader that installing the library makes `/pipeline/connectors`
20
- * answer, and it does not: they would get a 404 with nothing to point at.
15
+ * Connectors, transforms and access are the other shape, and what makes them so
16
+ * is not that nothing serves them. It is that WHERE they are served is the
17
+ * host's decision, which a frozen builder cannot express:
18
+ *
19
+ * - Connectors, transforms, workflows and runs are served by
20
+ * `createPipelineController`, which ships in
21
+ * `@dudousxd/nestjs-catalog-pipeline` — a *separate* package, mounted under
22
+ * whatever `path` its `forRoot` was given, and mounted nowhere at all if it
23
+ * was given none. Installing `@dudousxd/nestjs-catalog` does not make
24
+ * `/pipeline/connectors` answer, so putting `pipelineRoutes` beside
25
+ * `catalogRoutes` would tell a reader it does, and they would get a 404 with
26
+ * nothing to point at.
27
+ * - Access is the one that used to be described here as having no controller
28
+ * either, and it does have one: `createAccessController` is in the catalog
29
+ * library and `CatalogModule.forRoot` mounts it unless the host passes
30
+ * `controller: false`. What it does not have is a fixed path — it mounts
31
+ * under `accessPath`, a sibling of the catalog's own mount point — so it is
32
+ * still a default rather than a promise, for the second reason rather than
33
+ * the first.
21
34
  *
22
35
  * So the builders live here, in the package that ships the screens that need
23
36
  * them, and are stated as a *default* the host can move. The defaults are
@@ -25,11 +38,25 @@
25
38
  * `/api/pipeline` — because the transport is what knows the API prefix, and a
26
39
  * screen that hardcoded one app's mount point would be unusable in the next app.
27
40
  *
41
+ * The two load-expectation paths are the case that says what the rule above
42
+ * really is. They are served by that same pipeline controller in that same
43
+ * separate package, yet their builder — `pipelineExpectationRoutes` — is in
44
+ * `@dudousxd/nestjs-catalog/client`, and `pipelineRoutes` below borrows it
45
+ * instead of writing the strings again. That is not an exception, because the
46
+ * test was never which package a builder lives in: it is whether the builder
47
+ * takes a base path. `pipelineExpectationRoutes` does, so it promises nothing
48
+ * about where the routes are mounted no matter where it sits. It sits there
49
+ * because the wire types it goes with — `LoadExpectationInput`,
50
+ * `ResolvedLoadExpectation` — are declared in that entry point and the pipeline
51
+ * controller reads them from there too, and a path split from the shapes it
52
+ * returns is how the two halves of one contract come to be moved separately.
53
+ *
28
54
  * What this package therefore asks of a host is an HTTP surface with these
29
55
  * shapes, wherever it wants to mount it. That contract is the response types on
30
56
  * `CatalogClient` plus these paths, and a host that would rather satisfy it from
31
57
  * somewhere else entirely can pass its own base path, or replace the client.
32
58
  */
59
+ import { pipelineExpectationRoutes } from '@dudousxd/nestjs-catalog/client';
33
60
  /**
34
61
  * The embed API, which is the exception to everything above.
35
62
  *
@@ -97,6 +124,12 @@ function normalise(basePath) {
97
124
  }
98
125
  export function pipelineRoutes(basePath = DEFAULT_PIPELINE_BASE_PATH) {
99
126
  const base = normalise(basePath);
127
+ // The two expectation paths are BORROWED rather than written out again — two
128
+ // copies of a path is how a route ends up moved on one side and 404ing on the
129
+ // other. The header's load-expectation paragraph is why the copy that wins
130
+ // lives in `@dudousxd/nestjs-catalog/client` while everything else here is
131
+ // built in place.
132
+ const expectations = pipelineExpectationRoutes(base);
100
133
  return {
101
134
  capabilities: () => `${base}/capabilities`,
102
135
  connections: () => `${base}/connections`,
@@ -115,6 +148,8 @@ export function pipelineRoutes(basePath = DEFAULT_PIPELINE_BASE_PATH) {
115
148
  workflows: () => `${base}/workflows`,
116
149
  workflow: (id) => `${base}/workflows/${encodeURIComponent(id)}`,
117
150
  runWorkflow: (id) => `${base}/workflows/${encodeURIComponent(id)}/run`,
151
+ loadExpectations: () => expectations.expectations(),
152
+ loadExpectation: (typeName) => expectations.expectation(typeName),
118
153
  };
119
154
  }
120
155
  export function accessRoutes(basePath = DEFAULT_ACCESS_BASE_PATH) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dudousxd/nestjs-catalog-react",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
4
4
  "description": "Ready-made React screens for @dudousxd/nestjs-catalog — a model manager and a generic object explorer you can drop into your own app shell.",
5
5
  "license": "MIT",
6
6
  "author": "Davide Carvalho",
@@ -106,7 +106,7 @@
106
106
  "@tiptap/pm": "3.29.2",
107
107
  "tiptap-markdown": "0.9.0",
108
108
  "@tiptap/core": "3.29.2",
109
- "@dudousxd/nestjs-catalog": "0.12.0"
109
+ "@dudousxd/nestjs-catalog": "0.13.0"
110
110
  },
111
111
  "dependencies": {
112
112
  "clsx": "2.1.1",