@dudousxd/nestjs-catalog-react 0.32.0 → 0.34.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.
@@ -407,10 +407,20 @@ function FilterBar({ columns, filters, onChange, snapshots, snapshotId, onSnapsh
407
407
  : column.name,
408
408
  })) })), snapshots.length > 0 && (_jsxs("div", { className: "flex items-center gap-1.5", children: [_jsx(History, { size: 13, className: MUTED }), _jsx(Select, { value: snapshotId, onValueChange: onSnapshot, ariaLabel: "Load to read", className: "w-72", options: [
409
409
  { value: '', label: 'Current load' },
410
+ // A dropped load stays in the list — the record of it is kept on
411
+ // purpose — and says so in both lines rather than only in the
412
+ // error that picking it produces. `rowCount` is what it held when
413
+ // its rows went, so it is still worth showing: "1,204,880 rows,
414
+ // dropped" is the sentence somebody looking at disk needs, and it
415
+ // is not a claim that they can be read.
410
416
  ...snapshots.map((each) => ({
411
417
  value: each.id,
412
- label: describeSnapshot(each),
413
- hint: `${each.rowCount.toLocaleString()} rows · ${each.principalId}`,
418
+ label: each.droppedAt
419
+ ? `${describeSnapshot(each)} — dropped`
420
+ : describeSnapshot(each),
421
+ hint: each.droppedAt
422
+ ? `${each.rowCount.toLocaleString()} rows, dropped · ${each.principalId}`
423
+ : `${each.rowCount.toLocaleString()} rows · ${each.principalId}`,
414
424
  })),
415
425
  ] })] })), filters.map((filter, index) => {
416
426
  const column = columns.find((each) => each.name === filter.property);
@@ -3192,11 +3192,27 @@ function refusalFacts(forName) {
3192
3192
  const codes = new Set(forName.map((ref) => callableWorkflowBlock(ref)?.code));
3193
3193
  const facts = [];
3194
3194
  if (codes.has('no-version'))
3195
- facts.push('no version announced — cannot be pinned');
3195
+ facts.push(noVersionFact(forName));
3196
3196
  if (codes.has('ambiguous-group'))
3197
3197
  facts.push('claimed by two groups — ambiguous');
3198
3198
  return facts;
3199
3199
  }
3200
+ /**
3201
+ * Which flavour of "no version" this is, in the few words a row has.
3202
+ *
3203
+ * `'observed'` means nothing described the workflow at all — it is on the list
3204
+ * because a live queue of that name exists, which is what a call would be routed
3205
+ * on and the whole of what is known. That is a weaker thing than a worker which
3206
+ * published a description and left the version out, and the row says which,
3207
+ * because they call for different reading: the first is "there is a queue here",
3208
+ * the second is "there is a worker here that did not say".
3209
+ */
3210
+ function noVersionFact(refs) {
3211
+ const described = refs.some((ref) => ref.evidence !== 'observed');
3212
+ return described
3213
+ ? 'no version announced — cannot be pinned'
3214
+ : 'live queue only, nothing declared — cannot be pinned';
3215
+ }
3200
3216
  /**
3201
3217
  * The versions announced for one name, one row each.
3202
3218
  *
@@ -3215,7 +3231,7 @@ function callableVersionOption(ref) {
3215
3231
  const block = callableWorkflowBlock(ref);
3216
3232
  const facts = [];
3217
3233
  if (block?.code === 'no-version')
3218
- facts.push('no version announced — cannot be pinned');
3234
+ facts.push(noVersionFact([ref]));
3219
3235
  if (block?.code === 'ambiguous-group')
3220
3236
  facts.push(`two groups (${groupsOf(ref).join(', ')}) — ambiguous`);
3221
3237
  if (ref.group)
@@ -4099,6 +4115,28 @@ function NodeInspector({ node, draft, transforms, connections, storage, typeOpti
4099
4115
  function SourceInspector({ node, connections, storage, canEdit, discovery, discoverable, onDiscovered, onChange, }) {
4100
4116
  const [source, setSource] = useState(() => sourceDraftFrom(node.config));
4101
4117
  const kind = toConnectorKind(node.sourceKind ?? 'http');
4118
+ /**
4119
+ * The history of the type a `catalog` source names, so the snapshot can be
4120
+ * chosen instead of looked up.
4121
+ *
4122
+ * The whole answer to the objection that naming a snapshot by id is friction —
4123
+ * see `SnapshotField`. Keyed on the type the field currently holds and asked
4124
+ * only for that kind, so no other source node makes a request; the same query
4125
+ * key the object explorer's picker uses, so opening both costs one fetch.
4126
+ *
4127
+ * A failure is not surfaced: the field falls back to accepting a typed id,
4128
+ * which is exactly what it does on a store with no history. A console that
4129
+ * cannot list snapshots must not be a console that cannot edit a graph.
4130
+ */
4131
+ const client = useCatalogClient();
4132
+ const namedType = kind === 'catalog' ? source.objectType.trim() : '';
4133
+ const { data: snapshots } = useQuery({
4134
+ queryKey: catalogQueryKeys.objectSnapshots(namedType),
4135
+ queryFn: () => client.snapshots(namedType),
4136
+ enabled: namedType.length > 0,
4137
+ staleTime: 30_000,
4138
+ retry: false,
4139
+ });
4102
4140
  const options = connectionOptionsFor(kind, connections);
4103
4141
  // A connection chosen for one kind is meaningless for another, so switching
4104
4142
  // the kind drops it rather than keeping an id the server would reject.
@@ -4146,5 +4184,5 @@ function SourceInspector({ node, connections, storage, canEdit, discovery, disco
4146
4184
  ? 'No connections of this kind yet. One is worth making when a second source needs the same address.'
4147
4185
  : viaConnection
4148
4186
  ? 'The connection supplies the address and the credential. What stays below is only what is specific to this load.'
4149
- : undefined }), _jsx(SourceConnectionCreator, { kind: kind, canEdit: canEdit, hasOptions: options.length > 0, onCreated: (connection) => push(source, { connectionId: connection.id }) })] })), _jsx(SourceFields, { kind: kind, draft: source, onChange: update, viaConnection: viaConnection, disabled: !canEdit, storage: storage }), _jsx(ReadModeFields, { kind: kind, mode: mode, onModeChange: (next) => push(source, { mode: next }), draft: source, onChange: update, disabled: !canEdit }), incremental && (_jsx("p", { className: cn('text-[11px] leading-relaxed', MUTED), children: "A watermark is kept per node, so two sources in the same graph reading incrementally do not overwrite each other's position." })), _jsx(SchemaDiscoveryPanel, { workflowId: discoverable.workflowId ?? '', nodeId: node.id, bridge: discovery, onDiscovered: onDiscovered, onSave: discoverable.onSave, saving: discoverable.saving, ...(discoverable.workflowId === undefined ? { disabledReason: discoverable.because } : {}) })] }));
4187
+ : undefined }), _jsx(SourceConnectionCreator, { kind: kind, canEdit: canEdit, hasOptions: options.length > 0, onCreated: (connection) => push(source, { connectionId: connection.id }) })] })), _jsx(SourceFields, { kind: kind, draft: source, onChange: update, viaConnection: viaConnection, disabled: !canEdit, storage: storage, snapshots: snapshots }), _jsx(ReadModeFields, { kind: kind, mode: mode, onModeChange: (next) => push(source, { mode: next }), draft: source, onChange: update, disabled: !canEdit }), incremental && (_jsx("p", { className: cn('text-[11px] leading-relaxed', MUTED), children: "A watermark is kept per node, so two sources in the same graph reading incrementally do not overwrite each other's position." })), _jsx(SchemaDiscoveryPanel, { workflowId: discoverable.workflowId ?? '', nodeId: node.id, bridge: discovery, onDiscovered: onDiscovered, onSave: discoverable.onSave, saving: discoverable.saving, ...(discoverable.workflowId === undefined ? { disabledReason: discoverable.because } : {}) })] }));
4150
4188
  }
@@ -1,4 +1,4 @@
1
- import type { ConnectorKind } from '@dudousxd/nestjs-catalog/client';
1
+ import type { ConnectorKind, SnapshotRef } from '@dudousxd/nestjs-catalog/client';
2
2
  import { type ConnectableKind } from './connection-form';
3
3
  import { type StorageAvailability } from './workflow/model';
4
4
  /** A select hands back a string. Narrow it rather than promise it is a kind. */
@@ -73,8 +73,16 @@ export interface SourceDraft {
73
73
  forcePathStyle: boolean;
74
74
  maxObjectsPerRun: string;
75
75
  watermarkColumn: string;
76
- /** The object type a `catalog` source reads. Its whole configuration. */
76
+ /** The object type a `catalog` source reads. */
77
77
  objectType: string;
78
+ /**
79
+ * Which snapshot of it, when the node names one.
80
+ *
81
+ * Blank is the ordinary case and means the snapshot the type is currently
82
+ * serving — see {@link CATALOG_SOURCE_SNAPSHOT_KEY} for why that default has
83
+ * no spelling of its own.
84
+ */
85
+ objectSnapshot: string;
78
86
  }
79
87
  export declare function sourceDraftFrom(config: Record<string, unknown> | undefined): SourceDraft;
80
88
  /**
@@ -106,7 +114,7 @@ export interface SourceConfigOptions {
106
114
  * stale url on a SQL source, which reads as configuration somebody meant.
107
115
  */
108
116
  export declare function sourceConfigFrom(kind: ConnectorKind, draft: SourceDraft, { viaConnection, incremental }: SourceConfigOptions): Record<string, unknown>;
109
- export declare function SourceFields({ kind, draft, onChange, viaConnection, disabled, storage, }: {
117
+ export declare function SourceFields({ kind, draft, onChange, viaConnection, disabled, storage, snapshots, }: {
110
118
  kind: ConnectorKind;
111
119
  draft: SourceDraft;
112
120
  onChange: (draft: SourceDraft) => void;
@@ -119,6 +127,16 @@ export declare function SourceFields({ kind, draft, onChange, viaConnection, dis
119
127
  * {@link describeStorage}, which is what renders it.
120
128
  */
121
129
  storage?: StorageAvailability;
130
+ /**
131
+ * The history of the type a `catalog` source names, when the caller has it.
132
+ *
133
+ * Handed in rather than fetched here, exactly as `storage` is: this module is
134
+ * shared by two screens and has no transport of its own, and a component that
135
+ * reached for one would make the source form unusable anywhere the catalog
136
+ * client is not mounted. Absent falls back to a text field — see
137
+ * {@link SnapshotField}.
138
+ */
139
+ snapshots?: SnapshotRef[];
122
140
  }): import("react/jsx-runtime").JSX.Element;
123
141
  /** Full or incremental, with the per-kind explanation of what that means. */
124
142
  export declare function ReadModeFields({ kind, mode, onModeChange, draft, onChange, disabled, }: {
@@ -1,5 +1,5 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
- import { CATALOG_SOURCE_TYPE_KEY, CONNECTOR_KINDS, SOURCE_FORMATS, } from '@dudousxd/nestjs-catalog/client';
2
+ import { CATALOG_SOURCE_SNAPSHOT_KEY, CATALOG_SOURCE_TYPE_KEY, CONNECTOR_KINDS, SOURCE_FORMATS, catalogSnapshotRefusal, } from '@dudousxd/nestjs-catalog/client';
3
3
  import { cn } from './cn';
4
4
  import { CONNECTION_KINDS } from './connection-form';
5
5
  import { FieldGroup, TextAreaField, TextField } from './ui/field';
@@ -134,6 +134,7 @@ export function sourceDraftFrom(config) {
134
134
  maxObjectsPerRun: typeof source.maxObjectsPerRun === 'number' ? String(source.maxObjectsPerRun) : '',
135
135
  watermarkColumn: text('watermarkColumn'),
136
136
  objectType: text(CATALOG_SOURCE_TYPE_KEY),
137
+ objectSnapshot: text(CATALOG_SOURCE_SNAPSHOT_KEY),
137
138
  };
138
139
  }
139
140
  export function parseRecords(text) {
@@ -212,6 +213,23 @@ function s3Config(draft, viaConnection) {
212
213
  ...(draft.maxObjectsPerRun ? { maxObjectsPerRun: Number(draft.maxObjectsPerRun) } : {}),
213
214
  };
214
215
  }
216
+ /**
217
+ * The type, and the snapshot of it only when one was named.
218
+ *
219
+ * **Omitted rather than sent empty**, which is the entire reason this is a
220
+ * function and not an object literal at the call site. A blank field stored as
221
+ * `objectSnapshot: ""` would mean the current snapshot and read as one — and it
222
+ * would also be a config key that was not there before, so `workflowGraphHash`
223
+ * would fingerprint the node differently and present every graph somebody merely
224
+ * opened as a new version of itself. Absent is how "the current one" is spelled.
225
+ */
226
+ function catalogConfig(draft) {
227
+ const snapshot = draft.objectSnapshot.trim();
228
+ return {
229
+ [CATALOG_SOURCE_TYPE_KEY]: draft.objectType.trim(),
230
+ ...(snapshot.length === 0 ? {} : { [CATALOG_SOURCE_SNAPSHOT_KEY]: snapshot }),
231
+ };
232
+ }
215
233
  /**
216
234
  * The pasted records, or none when the text will not parse.
217
235
  *
@@ -239,7 +257,7 @@ export function sourceConfigFrom(kind, draft, { viaConnection, incremental }) {
239
257
  if (kind === 's3')
240
258
  return s3Config(draft, viaConnection);
241
259
  if (kind === 'catalog')
242
- return { [CATALOG_SOURCE_TYPE_KEY]: draft.objectType.trim() };
260
+ return catalogConfig(draft);
243
261
  return inlineConfig(draft);
244
262
  }
245
263
  /*
@@ -272,10 +290,88 @@ export function sourceConfigFrom(kind, draft, { viaConnection, incremental }) {
272
290
  * mapped back to `''` on the way into the draft.
273
291
  */
274
292
  const NO_DISK = '__no_disk__';
275
- export function SourceFields({ kind, draft, onChange, viaConnection, disabled, storage, }) {
293
+ /** The value of the "read whatever is being served" choice, for the same reason. */
294
+ const CURRENT_SNAPSHOT = '__current_snapshot__';
295
+ /**
296
+ * A snapshot's date, for a row in the picker.
297
+ *
298
+ * The id is what gets stored and it is a run id — `wf-9ff572d8` — which nobody
299
+ * can order in their head. The date is what somebody is actually choosing by, so
300
+ * it leads and the id follows on the hint line.
301
+ */
302
+ function snapshotLabel(snapshot) {
303
+ const at = new Date(snapshot.createdAt);
304
+ if (Number.isNaN(at.getTime()))
305
+ return snapshot.id;
306
+ return at.toLocaleString(undefined, {
307
+ year: 'numeric',
308
+ month: 'short',
309
+ day: '2-digit',
310
+ hour: '2-digit',
311
+ minute: '2-digit',
312
+ });
313
+ }
314
+ /**
315
+ * Which snapshot of the type this source reads.
316
+ *
317
+ * ## A list where there is one, a text field where there is not
318
+ *
319
+ * The list is the reason relative references are not supported. "The one before
320
+ * current" is a real thing to want and the objection to it is that it resolves
321
+ * differently on every run — but the friction it was going to relieve was
322
+ * *having to look an id up*, and that friction is this control's whole job. An
323
+ * id chosen from a list of dates is not looked up at all.
324
+ *
325
+ * The text field is the fallback rather than the primary, and it stays for two
326
+ * cases the list cannot cover: a type whose name has been typed but not yet
327
+ * published, and a graph being edited on a console that cannot see this
328
+ * catalog's history.
329
+ *
330
+ * ## A dropped snapshot is shown, and cannot be chosen
331
+ *
332
+ * Shown because the record is kept on purpose and hiding it would make a load
333
+ * that visibly happened look like one that never did. Unchoosable because its
334
+ * rows are gone and every read of it is refused — offering it and then refusing
335
+ * is a worse screen than one that says so up front. The same rule the object
336
+ * explorer's history picker follows, for the same reason.
337
+ */
338
+ function SnapshotField({ value, onChange, snapshots, disabled, }) {
339
+ const refusal = catalogSnapshotRefusal(value);
340
+ const listed = snapshots ?? [];
341
+ // A named snapshot that is not in the list — an id typed by hand, or one older
342
+ // than the window the list covers. Carried as its own row so choosing anything
343
+ // else and changing one's mind is not a one-way door.
344
+ const orphan = value.trim().length > 0 && !listed.some((each) => each.id === value.trim());
345
+ if (listed.length === 0) {
346
+ return (_jsx(TextField, { label: "Snapshot (optional)", value: value, onChange: onChange, placeholder: "Blank reads the current load", disabled: disabled, hint: refusal ? (_jsx("span", { className: "text-red-600 dark:text-red-400", children: refusal })) : ('Blank reads the snapshot the catalog is currently serving, resolved when the run starts. Name one snapshot id to read that load instead — an id, never "latest" or "previous", because a name that resolves at run time reads different data on different days without the graph changing.') }));
347
+ }
348
+ return (_jsxs("div", { className: "space-y-1", children: [_jsx(SelectField, { label: "Snapshot", ariaLabel: "Which snapshot to read", value: value.trim().length === 0 ? CURRENT_SNAPSHOT : value.trim(), onValueChange: (next) => onChange(next === CURRENT_SNAPSHOT ? '' : next), options: [
349
+ {
350
+ value: CURRENT_SNAPSHOT,
351
+ label: 'Current load',
352
+ hint: 'Resolved when the run starts',
353
+ },
354
+ ...(orphan
355
+ ? [{ value: value.trim(), label: value.trim(), hint: 'Not in this history' }]
356
+ : []),
357
+ ...listed.map((snapshot) => ({
358
+ value: snapshot.id,
359
+ label: snapshot.droppedAt
360
+ ? `${snapshotLabel(snapshot)} — dropped`
361
+ : snapshotLabel(snapshot),
362
+ hint: snapshot.droppedAt
363
+ ? `${snapshot.rowCount.toLocaleString()} rows, dropped · ${snapshot.id}`
364
+ : `${snapshot.rowCount.toLocaleString()} rows · ${snapshot.id}`,
365
+ // The rows are gone. Offering it and refusing the run is the screen
366
+ // this avoids.
367
+ disabled: Boolean(snapshot.droppedAt),
368
+ })),
369
+ ], disabled: disabled, hint: "A named snapshot is pinned by the name itself, so every run of this graph reads the same load. Leave it on the current load and the run resolves what the catalog is serving when it starts." }), refusal && (_jsx("p", { className: "text-[11px] leading-relaxed text-red-600 dark:text-red-400", children: refusal }))] }));
370
+ }
371
+ export function SourceFields({ kind, draft, onChange, viaConnection, disabled, storage, snapshots, }) {
276
372
  const set = (patch) => onChange({ ...draft, ...patch });
277
373
  if (kind === 'catalog') {
278
- return (_jsx(TextField, { label: "Object type", value: draft.objectType, onChange: (objectType) => set({ objectType }), placeholder: "e.g. SubwoReplica", disabled: disabled, hint: "The type, not a table. This reads the snapshot the catalog is currently serving, resolved when the run starts \u2014 the physical table keeps every load that has ever run, so naming it directly reads them all." }));
374
+ return (_jsxs("div", { className: "space-y-3", children: [_jsx(TextField, { label: "Object type", value: draft.objectType, onChange: (objectType) => set({ objectType }), placeholder: "e.g. SubwoReplica", disabled: disabled, hint: "The type, not a table. The physical table keeps every load that has ever run, so naming it directly reads them all." }), _jsx(SnapshotField, { value: draft.objectSnapshot, onChange: (objectSnapshot) => set({ objectSnapshot }), snapshots: snapshots, disabled: disabled })] }));
279
375
  }
280
376
  if (kind === 'http') {
281
377
  return (_jsxs("div", { className: "grid gap-3 sm:grid-cols-2", children: [!viaConnection && (_jsx(TextField, { label: "URL", value: draft.url, onChange: (url) => set({ url }), placeholder: "https://\u2026", disabled: disabled })), _jsx(TextField, { label: "Path to the array", value: draft.path, onChange: (path) => set({ path }), placeholder: "e.g. data", disabled: disabled })] }));
@@ -1,4 +1,4 @@
1
- import { CATALOG_SOURCE_TYPE_KEY, CONNECTOR_KINDS, isSafeIdentifier, physicalColumn, } from '@dudousxd/nestjs-catalog/client';
1
+ import { CATALOG_SOURCE_SNAPSHOT_KEY, CATALOG_SOURCE_TYPE_KEY, CONNECTOR_KINDS, isSafeIdentifier, physicalColumn, } from '@dudousxd/nestjs-catalog/client';
2
2
  export const SOURCE_KINDS = {
3
3
  http: {
4
4
  label: 'an HTTP endpoint',
@@ -51,7 +51,10 @@ export const SOURCE_KINDS = {
51
51
  catalog: {
52
52
  label: "this catalog's own data",
53
53
  required: [CATALOG_SOURCE_TYPE_KEY],
54
- optional: [],
54
+ // Naming a snapshot is the one optional thing this kind has, and no template
55
+ // ships one: a template describes a load that runs on a schedule, and a
56
+ // schedule pinned to one historical snapshot reads the same rows forever.
57
+ optional: [CATALOG_SOURCE_SNAPSHOT_KEY],
55
58
  // False, and it is the strongest `false` in this record. The rows come out
56
59
  // of the store keyed by the *property names of the type they were read
57
60
  // from* — that is what `read` and `streamSnapshot` both hand back — so there
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dudousxd/nestjs-catalog-react",
3
- "version": "0.32.0",
3
+ "version": "0.34.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",
@@ -110,7 +110,7 @@
110
110
  "tailwind-merge": "3.4.1",
111
111
  "tiptap-markdown": "0.9.0",
112
112
  "typescript": "5.9.3",
113
- "@dudousxd/nestjs-catalog": "0.28.0"
113
+ "@dudousxd/nestjs-catalog": "0.32.0"
114
114
  },
115
115
  "dependencies": {
116
116
  "clsx": "2.1.1",