@dudousxd/nestjs-catalog-react 0.27.0 → 0.28.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,5 +1,5 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
2
- import { isTransformLanguage, transformShape } from '@dudousxd/nestjs-catalog/client';
2
+ import { isTransformLanguage, isTransformMode, recordModeRefusal, transformMode, transformShape, } from '@dudousxd/nestjs-catalog/client';
3
3
  import { useMutation } from '@tanstack/react-query';
4
4
  import { ArrowLeft, Play } from 'lucide-react';
5
5
  import { useState } from 'react';
@@ -72,6 +72,63 @@ return [{
72
72
  "critical": int(r["risk"]) >= 80,
73
73
  } for r in records]`,
74
74
  };
75
+ /**
76
+ * Starter code for the per-record mode.
77
+ *
78
+ * A second table rather than a branch inside the first, so that adding a
79
+ * language without a per-record starter is a type error in the same way adding
80
+ * one without a batch starter already is.
81
+ *
82
+ * Python is absent from this table and cannot be here: its harness writes
83
+ * `def transform(records, context):` and there is no second `def` yet, which is
84
+ * why `recordModeRefusal` refuses the combination outright. The type says so —
85
+ * the key set is the two languages the mode can actually run in — rather than
86
+ * carrying a starter for a mode the server will reject.
87
+ */
88
+ const RECORD_STARTERS = {
89
+ typescript: `import type { CatalogRecordTransformFunction } from '@dudousxd/nestjs-catalog/client';
90
+
91
+ // One record in, one row out. This runs once per record over a stream, so
92
+ // nothing anywhere holds the whole read — see the mode selector above.
93
+ type Source = { tag: string; risk: string; kind: string };
94
+
95
+ const transform: CatalogRecordTransformFunction<Source> = ({ record, context }) => ({
96
+ assetId: record.tag,
97
+ riskScore: Number(record.risk),
98
+ vehicleTypeName: record.kind.toUpperCase(),
99
+ critical: Number(record.risk) >= 80,
100
+ });
101
+
102
+ export default transform;`,
103
+ javascript: `// One record in, one row out — this runs once per record over a stream.
104
+ // Return an array to turn one record into several, or null to drop it.
105
+ export default function transform({ record, context }) {
106
+ return {
107
+ assetId: record.tag,
108
+ riskScore: Number(record.risk),
109
+ vehicleTypeName: String(record.kind).toUpperCase(),
110
+ critical: Number(record.risk) >= 80,
111
+ };
112
+ }`,
113
+ };
114
+ /**
115
+ * What an empty editor opens with, for this language in this mode.
116
+ *
117
+ * One function so the two tables are consulted in one place. A per-record
118
+ * Python transform has no starter because it has no harness; it falls back to
119
+ * the batch one, and `recordModeRefusal` is what tells the author why the
120
+ * combination cannot be saved — a starter that pretended otherwise would be the
121
+ * editor teaching a shape the server refuses.
122
+ */
123
+ function starterFor(language, mode) {
124
+ if (mode === 'record' && language !== 'python')
125
+ return RECORD_STARTERS[language];
126
+ return STARTERS[language];
127
+ }
128
+ /** Every starter, so "has this been edited" can be asked without listing them. */
129
+ function isUntouchedStarter(code) {
130
+ return Object.values(STARTERS).includes(code) || Object.values(RECORD_STARTERS).includes(code);
131
+ }
75
132
  const SAMPLE = `[
76
133
  { "tag": "AF93E00073", "risk": "88", "kind": "truck" },
77
134
  { "tag": "AF00D00169", "risk": "12", "kind": "sedan" }
@@ -113,13 +170,18 @@ function TryOutput({ result, error }) {
113
170
  * Not shown for Python, which has one shape and no rule: its harness writes the
114
171
  * `def` itself, so there is nothing here for an author to have got wrong.
115
172
  */
116
- function ShapeBadge({ language, code }) {
173
+ function ShapeBadge({ language, code, mode, }) {
117
174
  if (language === 'python')
118
175
  return null;
119
176
  const shape = transformShape(code);
120
177
  const isModule = shape === 'module';
178
+ // The argument named in the tooltip follows the selected mode, because that is
179
+ // what the harness will actually pass. A badge that said `{ records, context }`
180
+ // beside a per-record selector would be reassuring somebody about a call that
181
+ // is not going to happen.
182
+ const argument = mode === 'record' ? '{ record, context }' : '{ records, context }';
121
183
  return (_jsx(Tooltip, { content: isModule
122
- ? 'A top-level `export`, so this is imported as a module and its default export (or an export named `transform`) is called with one object: { records, context }. Fields can be added to that object later without changing this signature.'
184
+ ? `A top-level \`export\`, so this is imported as a module and its default export (or an export named \`transform\`) is called with one object: ${argument}. Fields can be added to that object later without changing this signature.`
123
185
  : 'No top-level `export`, so this runs as the body of a function that already has `records` and `context` in scope. Supported and unchanged — `export default function transform({ records, context })` is the shape that can gain fields later.', children: _jsx("span", { className: cn('cursor-default rounded border px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-[0.14em]', RULE, MUTED), children: isModule ? 'function' : 'bare body' }) }));
124
186
  }
125
187
  /**
@@ -130,15 +192,16 @@ function ShapeBadge({ language, code }) {
130
192
  * the code it was pinned to — and it should be visible before the click, not
131
193
  * explained after it.
132
194
  */
133
- function SaveBar({ transform, nameIsEmpty, pending, error, onSave, }) {
134
- return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("button", { type: "button", onClick: onSave, disabled: pending || nameIsEmpty, className: cn('rounded-md border px-3 py-1.5 text-xs disabled:opacity-40', RULE, 'hover:bg-zinc-50 dark:hover:bg-zinc-800'), children: pending ? 'Saving…' : transform ? 'Save changes' : 'Save transform' }), transform && (_jsxs("span", { className: cn('font-mono text-[10px]', MUTED), children: ["saving new code makes this v", transform.version + 1] })), error ? (_jsx("span", { className: "text-[11px] text-red-600", children: error instanceof Error ? error.message : 'Could not save.' })) : null] }));
195
+ function SaveBar({ transform, nameIsEmpty, refused, pending, error, onSave, }) {
196
+ return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("button", { type: "button", onClick: onSave, disabled: pending || nameIsEmpty || refused, className: cn('rounded-md border px-3 py-1.5 text-xs disabled:opacity-40', RULE, 'hover:bg-zinc-50 dark:hover:bg-zinc-800'), children: pending ? 'Saving…' : transform ? 'Save changes' : 'Save transform' }), transform && (_jsxs("span", { className: cn('font-mono text-[10px]', MUTED), children: ["saving new code makes this v", transform.version + 1] })), error ? (_jsx("span", { className: "text-[11px] text-red-600", children: error instanceof Error ? error.message : 'Could not save.' })) : null] }));
135
197
  }
136
198
  export function TransformEditor({ transform, languages, pythonPackages = [], onClose, onSaved, }) {
137
199
  const client = useCatalogClient();
138
200
  const [name, setName] = useState(transform?.name ?? '');
139
201
  const [description, setDescription] = useState(transform?.description ?? '');
140
202
  const [language, setLanguage] = useState(transform?.language ?? languages[0] ?? 'javascript');
141
- const [code, setCode] = useState(transform?.code ?? STARTERS[transform?.language ?? 'javascript']);
203
+ const [mode, setMode] = useState(transform ? transformMode(transform) : 'batch');
204
+ const [code, setCode] = useState(transform?.code ?? starterFor(transform?.language ?? 'javascript', 'batch'));
142
205
  const [sample, setSample] = useState(SAMPLE);
143
206
  const [historyOpen, setHistoryOpen] = useState(false);
144
207
  const tryIt = useMutation({
@@ -154,7 +217,11 @@ export function TransformEditor({ transform, languages, pythonPackages = [], onC
154
217
  // person reading it would go looking at their transform.
155
218
  throw new Error('The sample is not valid JSON.');
156
219
  }
157
- return client.tryTransform({ language, code, records });
220
+ // The mode goes with it, so the pane runs the code under the contract the
221
+ // author has selected rather than under whichever one the server would
222
+ // default to. A per-record transform tried as a batch is handed the whole
223
+ // array as its `record` and shows empty rows for correct code.
224
+ return client.tryTransform({ language, code, records, mode });
158
225
  },
159
226
  });
160
227
  const save = useMutation({
@@ -163,10 +230,14 @@ export function TransformEditor({ transform, languages, pythonPackages = [], onC
163
230
  name: name.trim(),
164
231
  language,
165
232
  code,
233
+ mode,
166
234
  description: description.trim() || undefined,
167
235
  }),
168
236
  onSuccess: onSaved,
169
237
  });
238
+ // The same question the controller asks, from the same function, so the
239
+ // editor and the server cannot disagree about which combinations are legal.
240
+ const refusal = recordModeRefusal({ language, code, mode });
170
241
  // `preventDefault` is what claims the key. The editor's default keymap binds
171
242
  // ⌘↵ to "insert a blank line", and `CodeEditor` only withholds a keystroke
172
243
  // from it when the host has said it wants it — so without this, trying the
@@ -185,20 +256,30 @@ export function TransformEditor({ transform, languages, pythonPackages = [], onC
185
256
  setLanguage(value);
186
257
  // Only replace untouched starter code — silently discarding
187
258
  // somebody's work because they changed a dropdown would be rude.
188
- if (Object.values(STARTERS).includes(code)) {
189
- setCode(STARTERS[value]);
190
- }
259
+ if (isUntouchedStarter(code))
260
+ setCode(starterFor(value, mode));
191
261
  }, options: languages.map((option) => ({
192
262
  value: option,
193
263
  label: option,
194
- })) })] }), _jsxs("div", { className: "grid gap-3 lg:grid-cols-2", children: [_jsxs("div", { className: cn('overflow-hidden rounded-lg border', RULE, PANEL), children: [_jsxs("div", { className: cn('flex items-center justify-between border-b px-3 py-1.5', RULE), children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: cn('font-mono text-[10px] uppercase tracking-[0.14em]', MUTED), children: "Code" }), _jsx(ShapeBadge, { language: language, code: code })] }), _jsx("span", { className: cn('font-mono text-[10px]', MUTED), children: language === 'python' && pythonPackages.length > 0
264
+ })) })] }), _jsxs("div", { className: "grid gap-3 sm:grid-cols-3", children: [_jsx(SelectField, { label: "Called", ariaLabel: "Called", value: mode, onValueChange: (value) => {
265
+ if (!isTransformMode(value))
266
+ return;
267
+ setMode(value);
268
+ if (isUntouchedStarter(code))
269
+ setCode(starterFor(language, value));
270
+ }, options: [
271
+ { value: 'batch', label: 'once with the whole batch' },
272
+ { value: 'record', label: 'once per record (streams)' },
273
+ ] }), _jsx("p", { className: cn('sm:col-span-2 self-center text-xs leading-relaxed', MUTED), children: mode === 'record'
274
+ ? 'Each record is mapped on its own and the rows are written as they are produced, so nothing holds the whole read. Return one object, an array of them, or null to drop the record. Aggregating, deduplicating and sorting need the whole batch and cannot be written this way.'
275
+ : 'The code is called once with every record, which is what aggregating, deduplicating, sorting and joining need. The whole read is held in memory while it runs.' })] }), refusal ? (_jsx("p", { className: "rounded-lg border border-amber-300 bg-amber-50 px-3 py-2 text-xs leading-relaxed text-amber-900 dark:border-amber-900/60 dark:bg-amber-950/40 dark:text-amber-200", children: refusal })) : null, _jsxs("div", { className: "grid gap-3 lg:grid-cols-2", children: [_jsxs("div", { className: cn('overflow-hidden rounded-lg border', RULE, PANEL), children: [_jsxs("div", { className: cn('flex items-center justify-between border-b px-3 py-1.5', RULE), children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: cn('font-mono text-[10px] uppercase tracking-[0.14em]', MUTED), children: "Code" }), _jsx(ShapeBadge, { language: language, code: code, mode: mode })] }), _jsx("span", { className: cn('font-mono text-[10px]', MUTED), children: language === 'python' && pythonPackages.length > 0
195
276
  ? `imports: ${pythonPackages.join(', ')}`
196
277
  : '⌘↵ to try' })] }), _jsx(CodeEditor, { value: code, onChange: setCode, onKeyDown: onKeyDown,
197
278
  // A table rather than the `language === 'python' ? 'python' : 'tsx'`
198
279
  // that used to be here. The ternary answered a fourth transform
199
280
  // language with `tsx` — silently, and wrongly — where the table
200
281
  // cannot be indexed by one at all until somebody adds the row.
201
- language: TRANSFORM_HIGHLIGHTED_AS[language], label: "Transform code", className: "h-72" })] }), _jsxs("div", { className: "space-y-3", children: [_jsxs("div", { className: cn('overflow-hidden rounded-lg border', RULE, PANEL), children: [_jsx("div", { className: cn('border-b px-3 py-1.5', RULE), children: _jsx("span", { className: cn('font-mono text-[10px] uppercase tracking-[0.14em]', MUTED), children: "Sample records" }) }), _jsx(CodeEditor, { value: sample, onChange: setSample, language: "json", label: "Sample records", className: "h-32" })] }), _jsxs("button", { type: "button", onClick: () => tryIt.mutate(), disabled: tryIt.isPending, className: "flex items-center gap-1.5 rounded-md bg-zinc-950 px-3 py-1.5 text-xs text-zinc-50 disabled:opacity-40 dark:bg-zinc-100 dark:text-zinc-950", children: [_jsx(Play, { size: 12 }), tryIt.isPending ? 'Running…' : 'Try it'] }), _jsxs("div", { className: cn('overflow-hidden rounded-lg border', RULE, PANEL), children: [_jsx("div", { className: cn('border-b px-3 py-1.5', RULE), children: _jsx("span", { className: cn('font-mono text-[10px] uppercase tracking-[0.14em]', MUTED), children: "Output" }) }), _jsx(TryOutput, { result: tryIt.data, error: tryIt.error })] })] })] }), _jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsx(SaveBar, { transform: transform, nameIsEmpty: name.trim().length === 0, pending: save.isPending, error: save.error, onSave: () => save.mutate() }), transform && (_jsx(RevisionHistoryButton, { className: "ml-auto", onClick: () => setHistoryOpen(true) }))] }), transform && (_jsx(RevisionHistorySheet, { open: historyOpen, onOpenChange: setHistoryOpen, subject: { kind: 'transform', id: transform.id, name: transform.name },
282
+ language: TRANSFORM_HIGHLIGHTED_AS[language], label: "Transform code", className: "h-72" })] }), _jsxs("div", { className: "space-y-3", children: [_jsxs("div", { className: cn('overflow-hidden rounded-lg border', RULE, PANEL), children: [_jsx("div", { className: cn('border-b px-3 py-1.5', RULE), children: _jsx("span", { className: cn('font-mono text-[10px] uppercase tracking-[0.14em]', MUTED), children: "Sample records" }) }), _jsx(CodeEditor, { value: sample, onChange: setSample, language: "json", label: "Sample records", className: "h-32" })] }), _jsxs("button", { type: "button", onClick: () => tryIt.mutate(), disabled: tryIt.isPending, className: "flex items-center gap-1.5 rounded-md bg-zinc-950 px-3 py-1.5 text-xs text-zinc-50 disabled:opacity-40 dark:bg-zinc-100 dark:text-zinc-950", children: [_jsx(Play, { size: 12 }), tryIt.isPending ? 'Running…' : 'Try it'] }), _jsxs("div", { className: cn('overflow-hidden rounded-lg border', RULE, PANEL), children: [_jsx("div", { className: cn('border-b px-3 py-1.5', RULE), children: _jsx("span", { className: cn('font-mono text-[10px] uppercase tracking-[0.14em]', MUTED), children: "Output" }) }), _jsx(TryOutput, { result: tryIt.data, error: tryIt.error })] })] })] }), _jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [_jsx(SaveBar, { refused: refusal !== undefined, transform: transform, nameIsEmpty: name.trim().length === 0, pending: save.isPending, error: save.error, onSave: () => save.mutate() }), transform && (_jsx(RevisionHistoryButton, { className: "ml-auto", onClick: () => setHistoryOpen(true) }))] }), transform && (_jsx(RevisionHistorySheet, { open: historyOpen, onOpenChange: setHistoryOpen, subject: { kind: 'transform', id: transform.id, name: transform.name },
202
283
  // The SAVED code, not what is in the editor above. A history is what
203
284
  // this catalog has recorded; comparing against an unsaved buffer would
204
285
  // put a version number on text that exists only in one browser tab,
package/dist/context.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { CallableWorkflowRef, CatalogAuditEvent, CatalogConnection, CatalogConnector, CatalogObjectPage, CatalogQueryRelation, CatalogQueryResult, CatalogReusableNode, CatalogRevision, CatalogSearchResult, CatalogSnapshot, CatalogTrace, CatalogTraceList, CatalogTransform, ConnectionCheck, ConnectorRun, Dashboard, DashboardCard, DeleteReconciliation, LoadExpectation, LoadExpectationInput, ObjectQueryParams, PropertyPatch, ResolvedLoadExpectation, ReusableNodeBody, RowCountBound, SaveQueryInput, SavedQuery, SnapshotRef, StoredLoadExpectation, TraceQuery, TransformLanguage, TransformResult, TypePatch } from '@dudousxd/nestjs-catalog/client';
1
+ import type { CallableWorkflowRef, CatalogAuditEvent, CatalogConnection, CatalogConnector, CatalogObjectPage, CatalogQueryRelation, CatalogQueryResult, CatalogReusableNode, CatalogRevision, CatalogSearchResult, CatalogSnapshot, CatalogTrace, CatalogTraceList, CatalogTransform, ConnectionCheck, ConnectorRun, Dashboard, DashboardCard, DeleteReconciliation, LoadExpectation, LoadExpectationInput, ObjectQueryParams, PropertyPatch, ResolvedLoadExpectation, ReusableNodeBody, RowCountBound, SaveQueryInput, SavedQuery, SnapshotRef, StoredLoadExpectation, TraceQuery, TransformLanguage, TransformMode, 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';
@@ -153,6 +153,16 @@ export interface TransformInput {
153
153
  description?: string;
154
154
  language: TransformLanguage;
155
155
  code: string;
156
+ /**
157
+ * Whether the code is called once with the batch or once per record.
158
+ *
159
+ * Optional, and **absent means "leave whatever is stored alone"** rather than
160
+ * "make it a batch". A caller written before this field existed sends no mode,
161
+ * and the store reads that as no instruction — so an older client saving a
162
+ * rename cannot silently undo somebody's deliberate choice. See
163
+ * `TRANSFORM_MODES`.
164
+ */
165
+ mode?: TransformMode;
156
166
  }
157
167
  /**
158
168
  * One pipeline that would break if a connection were deleted.
@@ -718,6 +728,15 @@ export interface CatalogClient {
718
728
  language: TransformLanguage;
719
729
  code: string;
720
730
  records: unknown[];
731
+ /**
732
+ * Which contract to run the sample under.
733
+ *
734
+ * Sent by the editor, because a pane that tried a per-record transform as a
735
+ * batch would hand it the whole array as its `record` and show empty rows
736
+ * for correct code — through the one screen whose value is that it predicts
737
+ * what the load will do.
738
+ */
739
+ mode?: TransformMode;
721
740
  }): Promise<TransformResult>;
722
741
  /**
723
742
  * Authored graphs: sources wired through transforms into sinks.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dudousxd/nestjs-catalog-react",
3
- "version": "0.27.0",
3
+ "version": "0.28.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.23.0"
113
+ "@dudousxd/nestjs-catalog": "0.24.0"
114
114
  },
115
115
  "dependencies": {
116
116
  "clsx": "2.1.1",