@dudousxd/nestjs-catalog-react 0.31.0 → 0.33.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.
@@ -7,7 +7,7 @@ import { Background, BackgroundVariant, ConnectionLineType, Controls, MiniMap, P
7
7
  // See src/styles.d.ts for why `tsc` tolerates this import.
8
8
  import '@xyflow/react/dist/style.css';
9
9
  import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
10
- import { ArrowRight, ChevronDown, CircleAlert, CircleDashed, Code2, Database, ExternalLink, Filter, GitBranch, Info, LayoutGrid, Loader2, Maximize2, Minimize2, PanelRight, Plug, Plus, Repeat, Save, Sigma, TextCursorInput, Trash2, TriangleAlert, Unplug, X, } from 'lucide-react';
10
+ import { ArrowRight, ChevronDown, CircleAlert, CircleDashed, Code2, Combine, Database, ExternalLink, Filter, GitBranch, Info, LayoutGrid, Loader2, Maximize2, Minimize2, PanelRight, Plug, Plus, Repeat, Save, Sigma, TextCursorInput, Trash2, TriangleAlert, Unplug, X, } from 'lucide-react';
11
11
  import { AnimatePresence, motion, useReducedMotion } from 'motion/react';
12
12
  import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
13
13
  import { connectionOptionsFor } from './ConnectionPanel';
@@ -32,7 +32,7 @@ import { defaultLabel, describeFilterPredicate, flowingEdgeIds, layout, layoutIf
32
32
  import { HistoryControls, keepKnown, namesOf, nodeEditAction, reverted, snapshotOf, undone, useUndoShortcut, useUnsavedGuard, withEdit, } from './workflow/history';
33
33
  import { PublishControls, RunControls, SchedulePanel, ShrinkRefusalNote, WorkflowStatusBadge, } from './workflow/lifecycle';
34
34
  import { CanvasContextMenu, NodeActionsToolbar } from './workflow/menu';
35
- import { WORKFLOW_AGGREGATE_FUNCTIONS, WORKFLOW_AGGREGATE_MAX_AGGREGATES, WORKFLOW_AGGREGATE_MAX_GROUP_BY, WORKFLOW_BRANCH_LABELS, WORKFLOW_CALL_MODES, WORKFLOW_FILTER_MAX_DEPTH, WORKFLOW_FILTER_MAX_VALUES, WORKFLOW_FILTER_OPERATORS, WORKFLOW_NODE_KINDS, WORKFLOW_RENAME_MAX_COLUMNS, aggregateRefusals, callableWorkflowBlock, describeDurability, isWorkflowAggregateFunction, isWorkflowBranchLabel, isWorkflowFilterOperator, isWorkflowFilterPredicateKind, isWorkflowNodeKind, isWorkflowPredicateKind, isWorkflowRenameUnnamed, newLocalId, nodeName, producedTypes, renameColumnRefusals, unreachableFilterPredicateKind, unreachableNodeKind, unreachablePredicateKind, workflowAggregateMaxGroups, workflowAggregateNeedsColumn, workflowAggregateOutputColumns, workflowCallMode, workflowKnownColumns, workflowNarrowedTypes, workflowRenameUnnamed, } from './workflow/model';
35
+ import { WORKFLOW_AGGREGATE_FUNCTIONS, WORKFLOW_AGGREGATE_MAX_AGGREGATES, WORKFLOW_AGGREGATE_MAX_GROUP_BY, WORKFLOW_BRANCH_LABELS, WORKFLOW_CALL_MODES, WORKFLOW_FILTER_MAX_DEPTH, WORKFLOW_FILTER_MAX_VALUES, WORKFLOW_FILTER_OPERATORS, WORKFLOW_LOOKUP_MAX_FIELDS, WORKFLOW_LOOKUP_MAX_REFERENCE_ROWS, WORKFLOW_NODE_KINDS, WORKFLOW_RENAME_MAX_COLUMNS, aggregateRefusals, callableWorkflowBlock, describeDurability, isWorkflowAggregateFunction, isWorkflowBranchLabel, isWorkflowFilterOperator, isWorkflowFilterPredicateKind, isWorkflowLookupUnmatched, isWorkflowNodeKind, isWorkflowPredicateKind, isWorkflowRenameUnnamed, lookupConfigRefusals, newLocalId, nodeName, producedTypes, renameColumnRefusals, unreachableFilterPredicateKind, unreachableNodeKind, unreachablePredicateKind, workflowAggregateMaxGroups, workflowAggregateNeedsColumn, workflowAggregateOutputColumns, workflowCallMode, workflowKnownColumns, workflowLookupColumns, workflowLookupUnmatched, workflowNarrowedTypes, workflowRenameUnnamed, } from './workflow/model';
36
36
  import { WORKFLOW_NAME } from './workflow/name';
37
37
  import { WorkflowNodeProvider, workflowNodeTypes } from './workflow/nodes';
38
38
  import { freeSpot, placeNextTo } from './workflow/place';
@@ -470,6 +470,11 @@ const ADD_NODE = {
470
470
  label: 'Aggregate',
471
471
  hint: 'Groups the rows and summarises each group — count, sum, average, min, max, or the values joined together. No code, and it holds only the groups rather than the rows, so a 44,720-row grouping into 16,119 groups never has more than one batch of records in memory. It refuses loudly if the grouping turns out to hold nearly everything.',
472
472
  },
473
+ lookup: {
474
+ icon: Combine,
475
+ label: 'Lookup',
476
+ hint: 'Brings fields across from a reference dataset, matched by key. Wire two things into it and say which one is the reference: that side is held in memory as a map, the other streams past it. The run says how many rows matched and how many did not, which is the difference between a working join and one that silently filled a column with nulls.',
477
+ },
473
478
  };
474
479
  /**
475
480
  * The value the workflow picker uses for "start a fresh one".
@@ -894,6 +899,12 @@ function miniMapColor(data) {
894
899
  // avoid, and the box on the map is where somebody notices there is one.
895
900
  if (kind === 'aggregate')
896
901
  return '#f59e0b';
902
+ // Indigo-500, the lookup's own accent (see `KIND_STYLE`). The overview is where
903
+ // somebody looks for the shape of a graph, and a lookup is the one box where
904
+ // two lines meet for different reasons — so it must not read as a source, which
905
+ // is what the wire feeding it usually is.
906
+ if (kind === 'lookup')
907
+ return '#6366f1';
897
908
  return '#8b5cf6';
898
909
  }
899
910
  /**
@@ -3181,11 +3192,27 @@ function refusalFacts(forName) {
3181
3192
  const codes = new Set(forName.map((ref) => callableWorkflowBlock(ref)?.code));
3182
3193
  const facts = [];
3183
3194
  if (codes.has('no-version'))
3184
- facts.push('no version announced — cannot be pinned');
3195
+ facts.push(noVersionFact(forName));
3185
3196
  if (codes.has('ambiguous-group'))
3186
3197
  facts.push('claimed by two groups — ambiguous');
3187
3198
  return facts;
3188
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
+ }
3189
3216
  /**
3190
3217
  * The versions announced for one name, one row each.
3191
3218
  *
@@ -3204,7 +3231,7 @@ function callableVersionOption(ref) {
3204
3231
  const block = callableWorkflowBlock(ref);
3205
3232
  const facts = [];
3206
3233
  if (block?.code === 'no-version')
3207
- facts.push('no version announced — cannot be pinned');
3234
+ facts.push(noVersionFact([ref]));
3208
3235
  if (block?.code === 'ambiguous-group')
3209
3236
  facts.push(`two groups (${groupsOf(ref).join(', ')}) — ambiguous`);
3210
3237
  if (ref.group)
@@ -3538,6 +3565,77 @@ function AggregateInspector({ node, graph, canEdit, onChange, }) {
3538
3565
  commitRows(rows.map((each, at) => (at === index ? { ...each, maxLength } : each)));
3539
3566
  } }) })] }))] }, index))), canEdit && (_jsx(Button, { variant: "outline", size: "sm", onClick: () => commitRows([...rows, { as: '', fn: 'count' }]), disabled: rows.length >= WORKFLOW_AGGREGATE_MAX_AGGREGATES, children: "Add aggregate" }))] }), _jsxs("p", { className: cn('text-[11px] leading-relaxed', MUTED), children: ["This node holds ", _jsx("strong", { children: "one row per group" }), " and reads the records one staged batch at a time, so its memory is the number of groups and not the number of records. If the grouping turns out to be nearly one-to-one it holds the whole load, so the run", ' ', _jsx("strong", { children: "refuses" }), " past ", workflowAggregateMaxGroups(node).toLocaleString(), " groups rather than quietly filling the machine."] }), refusals.length > 0 && (_jsx("p", { className: "text-[11px] leading-relaxed text-amber-600 dark:text-amber-400", children: refusals.join(' ') })), duplicated.length > 0 && (_jsxs("p", { className: "text-[11px] leading-relaxed text-amber-600 dark:text-amber-400", children: [duplicated.map((as) => `“${as}”`).join(', '), " is used by more than one row. Two columns cannot share one name, and picking a winner would be a rule about which of your numbers survives."] })), produces.length > 0 && (_jsxs("p", { className: cn('text-[11px] leading-relaxed', MUTED), children: ["What leaves this node is exactly ", _jsx("span", { className: "font-mono", children: produces.join(', ') }), ", on every record \u2014 including where the answer is null. Every other column of every record stops here. That set is ", _jsx("strong", { children: "exact" }), " rather than a best guess, which is what lets a filter or a sink below this node be checked when the graph is saved."] })), known ? (_jsxs("p", { className: cn('text-[11px] leading-relaxed', MUTED), children: ["The graph knows exactly what arrives here:", ' ', _jsx("span", { className: "font-mono", children: [...known].join(', ') || 'nothing at all' }), ". A column named above that is not in that list is refused when this graph is saved, rather than found out when sixteen thousand rows come back as one."] })) : (_jsx("p", { className: cn('text-[11px] leading-relaxed', MUTED), children: "The graph cannot say which columns reach this node \u2014 a source discovers its shape against the live system, and a transform is code. So the column names above are taken on trust, and the run says out loud if one of them was in no record at all." }))] }));
3540
3567
  }
3568
+ /**
3569
+ * The lookup node's form: which input is the reference, the two key columns, and
3570
+ * the fields to bring across.
3571
+ *
3572
+ * ## Why the reference is a picker over inbound edges and not a text box
3573
+ *
3574
+ * Because the field is a node id, and a node id typed by hand is a graph that
3575
+ * saves and then either refuses at validation or — worse — names a node that
3576
+ * happens to exist and holds the wrong side of the join in memory. The picker is
3577
+ * built from this node's own inbound edges, so the only offerable answers are the
3578
+ * ones `validateWorkflow` accepts. With nothing wired in there is nothing to
3579
+ * offer, and the panel says that instead of showing an empty select somebody
3580
+ * would read as a bug.
3581
+ *
3582
+ * ## What the panel can say that no other inspector can
3583
+ *
3584
+ * Which columns are on **which side**. Every other node with several inputs sees
3585
+ * them pooled — the rows arrive concatenated — so "the columns reaching this
3586
+ * node" is one set. A lookup is the exception: the reference's columns never flow
3587
+ * on, so pooling them would offer a key column that only exists over there, and a
3588
+ * join on a column the driving rows do not have matches nothing on every row and
3589
+ * commits. `workflowLookupColumns` is core's answer to that, not this screen's.
3590
+ *
3591
+ * Both sides answer "unknown" often and that is stated rather than papered over,
3592
+ * the stance `RenameInspector` takes about the same question.
3593
+ *
3594
+ * ## The rows are local state, the record is derived
3595
+ *
3596
+ * The same argument `RenameInspector` makes at length: a half-typed key is a key,
3597
+ * and rebuilding a `Record` on every keystroke collapses two rows the moment they
3598
+ * are briefly equal.
3599
+ */
3600
+ function LookupInspector({ node, graph, canEdit, onChange, }) {
3601
+ const map = node.fields ?? {};
3602
+ const [rows, setRows] = useState(() => {
3603
+ const entries = Object.entries(map).map(([from, to]) => ({ from, to }));
3604
+ return entries.length > 0 ? entries : [{ from: '', to: '' }];
3605
+ });
3606
+ const commit = (next) => {
3607
+ setRows(next);
3608
+ const fields = {};
3609
+ for (const row of next)
3610
+ fields[row.from] = row.to;
3611
+ onChange({ ...node, fields });
3612
+ };
3613
+ const setUnmatched = (value) => {
3614
+ if (!isWorkflowLookupUnmatched(value))
3615
+ return;
3616
+ // Stored absent for `null`, so the default has one spelling and picking up
3617
+ // this release cannot renumber a graph nobody edited. The boundary
3618
+ // normalises the same way.
3619
+ onChange({ ...node, unmatched: value === 'null' ? undefined : value });
3620
+ };
3621
+ const feeds = (graph.edges ?? []).filter((edge) => edge.to === node.id).map((edge) => edge.from);
3622
+ const nameOf = (id) => (graph.nodes ?? []).find((each) => each.id === id)?.name ?? id;
3623
+ const { driving, reference } = workflowLookupColumns(graph, node);
3624
+ const refusals = lookupConfigRefusals(node);
3625
+ const duplicated = rows
3626
+ .map((row) => row.from)
3627
+ .filter((from, at, all) => from.length > 0 && all.indexOf(from) !== at);
3628
+ const unmatched = workflowLookupUnmatched(node);
3629
+ return (_jsxs("div", { className: "space-y-3", children: [feeds.length === 0 ? (_jsx("p", { className: "text-[11px] leading-relaxed text-amber-600 dark:text-amber-400", children: "Nothing is wired into this node yet. A lookup needs two inputs \u2014 the rows you want enriched, and the reference to match them against \u2014 and it has to be told which of them is the reference, because that is the side it holds in memory." })) : (_jsx(SelectField, { label: "Reference rows come from", ariaLabel: "Which input holds the reference rows", value: feeds.includes(node.reference) ? node.reference : '', onValueChange: (reference) => onChange({ ...node, reference }), disabled: !canEdit, options: feeds.map((id) => ({
3630
+ value: id,
3631
+ label: nameOf(id),
3632
+ hint: id === node.reference ? 'held in memory' : 'would be held in memory',
3633
+ })) })), _jsxs("p", { className: cn('text-[11px] leading-relaxed', MUTED), children: ["The reference is read once and held as a map, up to", ' ', WORKFLOW_LOOKUP_MAX_REFERENCE_ROWS.toLocaleString(), " rows; everything else wired in streams past it a batch at a time and never accumulates. Point this at the ", _jsx("em", { children: "smaller" }), " side \u2014 a run that would hold more than that refuses rather than filling the pod."] }), _jsxs("div", { className: "flex items-end gap-2", children: [_jsx("div", { className: "min-w-0 flex-1", children: _jsx(TextField, { label: "Match on (the rows being enriched)", value: typeof node.key === 'string' ? node.key : '', placeholder: "planId", disabled: !canEdit, onChange: (key) => onChange({ ...node, key }) }) }), _jsx("div", { className: "min-w-0 flex-1", children: _jsx(TextField, { label: "Against (the reference rows)", value: typeof node.referenceKey === 'string' ? node.referenceKey : '', placeholder: "Plan ID", disabled: !canEdit, onChange: (referenceKey) => onChange({ ...node, referenceKey }) }) })] }), _jsxs("p", { className: cn('text-[11px] leading-relaxed', MUTED), children: ["Keys are compared ", _jsx("strong", { children: "as text, exactly as written" }), " \u2014 no trimming, no case folding. That is deliberate: deciding that ", _jsx("code", { children: "21 CES" }), " and ", _jsx("code", { children: "21CES" }), " are the same unit is a rule about your data, and it belongs in a transform on both sides where you can see it. A row with nothing in its key column is counted separately and never matches."] }), _jsxs(FieldGroup, { title: "Bring across", hint: _jsxs(_Fragment, { children: ["The column on the reference rows, and the name it lands under. The reference name is whatever that side actually calls it \u2014 ", _jsx("code", { children: "Plan Name" }), " is fine. The new one has to be a name a column can have: letters, digits and underscore, starting with a letter or an underscore. Landing on a column the rows already have is expected and works: a published type declares its columns, so the ones you are filling arrive empty. A row that already holds a ", _jsx("em", { children: "value" }), " there stops the run rather than losing it."] }), children: [rows.map((row, index) => (_jsxs("div", { className: "flex items-end gap-2", children: [_jsx("div", { className: "min-w-0 flex-1", children: _jsx(TextField, { label: index === 0 ? 'On the reference' : '', value: row.from, placeholder: "Plan Name", disabled: !canEdit, onChange: (from) => commit(rows.map((each, at) => (at === index ? { ...each, from } : each))) }) }), _jsx("div", { className: "min-w-0 flex-1", children: _jsx(TextField, { label: index === 0 ? 'Lands as' : '', value: row.to, placeholder: "planName", disabled: !canEdit, onChange: (to) => commit(rows.map((each, at) => (at === index ? { ...each, to } : each))) }) }), canEdit && rows.length > 1 && (_jsx(Button, { variant: "ghost", size: "sm", className: "shrink-0", onClick: () => commit(rows.filter((_, at) => at !== index)), children: "Remove" }))] }, index))), canEdit && (_jsx(Button, { variant: "outline", size: "sm", onClick: () => commit([...rows, { from: '', to: '' }]), disabled: rows.length >= WORKFLOW_LOOKUP_MAX_FIELDS, children: "Add field" }))] }), _jsx(SelectField, { label: "Rows whose key matches nothing", ariaLabel: "What happens to a row whose key matches no reference row", value: unmatched, onValueChange: setUnmatched, disabled: !canEdit, options: [
3634
+ { value: 'null', label: 'Pass on, fields set to null', hint: 'a LEFT JOIN' },
3635
+ { value: 'drop', label: 'Drop the row', hint: 'an INNER JOIN — removes rows' },
3636
+ { value: 'fail', label: 'Fail this node', hint: 'the reference is a prerequisite' },
3637
+ ] }), _jsxs("p", { className: cn('text-[11px] leading-relaxed', MUTED), children: [unmatched === 'drop' ? (_jsxs(_Fragment, { children: ["Unmatched rows ", _jsx("strong", { children: "will not reach the next node" }), ", so this node also removes rows \u2014 a full sink below it publishes only what matched."] })) : unmatched === 'fail' ? (_jsxs(_Fragment, { children: ["The first unmatched row ", _jsx("strong", { children: "stops the run" }), ", naming the key it could not find. Choose this when the reference is meant to cover everything and a load that cannot be enriched is one that should not commit."] })) : (_jsx(_Fragment, { children: "Unmatched rows are passed on with these columns set to null \u2014 the same result as enriching by hand, with one difference that is the whole point of the node." })), ' ', "Either way the run says how many rows matched, how many had a key that matched nothing, and how many had no key at all. A join that matched nothing looks exactly like one that worked unless somebody counts."] }), refusals.length > 0 && (_jsx("p", { className: "text-[11px] leading-relaxed text-amber-600 dark:text-amber-400", children: refusals.join(' ') })), duplicated.length > 0 && (_jsxs("p", { className: "text-[11px] leading-relaxed text-amber-600 dark:text-amber-400", children: [duplicated.map((from) => `“${from}”`).join(', '), " appears more than once on the left. A reference column can only land under one name, so only the last row naming it is stored."] })), _jsx(LookupSidesNote, { driving: driving, reference: reference })] }));
3638
+ }
3541
3639
  /**
3542
3640
  * One aggregate, with its function changed and the fields that no longer apply
3543
3641
  * dropped.
@@ -3569,6 +3667,22 @@ const AGGREGATE_HINTS = {
3569
3667
  max: 'the greatest value — same comparison',
3570
3668
  join: 'the values run together, refusing past a length rather than truncating',
3571
3669
  };
3670
+ /**
3671
+ * Which columns the graph can prove are on each of a lookup's two sides.
3672
+ *
3673
+ * Its own component because it is the sentence that is *only* true of this node
3674
+ * kind: every other multi-input inspector could say "the columns reaching this
3675
+ * node" as one list, and saying that here would offer a key column that exists
3676
+ * only on the reference — a join that matches nothing on every row.
3677
+ *
3678
+ * Either side answering "unknown" is the ordinary case and is said out loud
3679
+ * rather than papered over, the stance `RenameInspector` takes about the same
3680
+ * question. `undefined` is not "no columns": treating it as empty would refuse
3681
+ * every lookup below a transform.
3682
+ */
3683
+ function LookupSidesNote({ driving, reference, }) {
3684
+ return (_jsxs("p", { className: cn('text-[11px] leading-relaxed', MUTED), children: [driving ? (_jsxs(_Fragment, { children: ["The graph knows exactly what reaches the rows being enriched:", ' ', _jsx("span", { className: "font-mono", children: [...driving].join(', ') || 'nothing at all' }), "."] })) : (_jsx(_Fragment, { children: "The graph cannot say which columns reach the rows being enriched \u2014 a source discovers its shape against the live system, and a transform is code \u2014 so the key is taken on trust and the run reports the counts." })), ' ', reference ? (_jsxs(_Fragment, { children: ["On the reference side it is", ' ', _jsx("span", { className: "font-mono", children: [...reference].join(', ') || 'nothing at all' }), "."] })) : (_jsx(_Fragment, { children: "The reference side is unknown for the same reason." }))] }));
3685
+ }
3572
3686
  function FilterInspector({ node, graph, canEdit, onChange, }) {
3573
3687
  // Core's answer, not this file's. A canvas that worked out its own set would
3574
3688
  // offer acknowledgements the server then refuses, which is a person ticking a
@@ -3910,6 +4024,13 @@ function KindInspector({ node, graph, transforms, connections, storage, typeOpti
3910
4024
  if (node.kind === 'aggregate') {
3911
4025
  return _jsx(AggregateInspector, { node: node, graph: graph, canEdit: canEdit, onChange: onChange });
3912
4026
  }
4027
+ if (node.kind === 'lookup') {
4028
+ // Given the whole graph, and it needs it more than any other inspector does:
4029
+ // a lookup's `reference` is a node id, so the form cannot even list the
4030
+ // choices without the edges — and `workflowLookupColumns` is what lets it say
4031
+ // which columns are on which side rather than pooling them.
4032
+ return (_jsx(LookupInspector, { node: node, graph: graph, canEdit: canEdit, onChange: onChange }, node.id));
4033
+ }
3913
4034
  if (node.kind === 'sink') {
3914
4035
  return (_jsx(SinkInspector, { node: node, typeOptions: typeOptions, canEdit: canEdit, modelHref: modelHref, onChange: onChange }));
3915
4036
  }
@@ -114,6 +114,31 @@ export function newNodeOfKind(kind, id, position, name) {
114
114
  position,
115
115
  };
116
116
  }
117
+ if (kind === 'lookup') {
118
+ // Every field blank, and the validator refuses it by name from the moment the
119
+ // node is dropped — the stance `filter` and `rename` take, and for the same
120
+ // reason one step sharper. A lookup has *four* things to fill in and three of
121
+ // them have a plausible-looking wrong default: a `reference` guessed from the
122
+ // first inbound edge would decide which side is held in memory, and a
123
+ // `key`/`referenceKey` pair guessed from a column both sides happen to share
124
+ // would author a join nobody chose. All three are silent when wrong.
125
+ //
126
+ // `unmatched` is left absent, which means null. That is the only one of the
127
+ // three dispositions that changes neither which rows exist nor whether the run
128
+ // finishes, so it is the one a node can start on before anybody has thought
129
+ // about it — and the run log reports the count either way, which is the part
130
+ // that stops it being a guess with consequences.
131
+ return {
132
+ id,
133
+ name,
134
+ kind: 'lookup',
135
+ reference: '',
136
+ key: '',
137
+ referenceKey: '',
138
+ fields: { '': '' },
139
+ position,
140
+ };
141
+ }
117
142
  if (kind === 'sink') {
118
143
  return { id, name, kind: 'sink', targetType: '', position };
119
144
  }
@@ -1,6 +1,6 @@
1
1
  import { WORKFLOW_NODE_HEIGHT, WORKFLOW_NODE_WIDTH, workflowColumnX, workflowRowY, workflowRunOrder, } from '@dudousxd/nestjs-catalog/client';
2
2
  import { MarkerType } from '@xyflow/react';
3
- import { nodeName, unreachableFilterPredicateKind, unreachableNodeKind, unreachablePredicateKind, workflowCallMode, workflowRenameUnnamed, } from './model';
3
+ import { nodeName, unreachableFilterPredicateKind, unreachableNodeKind, unreachablePredicateKind, workflowCallMode, workflowLookupUnmatched, workflowRenameUnnamed, } from './model';
4
4
  import { edgeId } from './validate';
5
5
  /**
6
6
  * Turning the stored graph into what React Flow draws, and back.
@@ -56,6 +56,8 @@ function subtitleFor(node, describe) {
56
56
  return renameSubtitle(node);
57
57
  if (node.kind === 'aggregate')
58
58
  return aggregateSubtitle(node);
59
+ if (node.kind === 'lookup')
60
+ return lookupSubtitle(node);
59
61
  if (node.kind === 'transform') {
60
62
  return describe.transformName(node.transformId) ?? 'no transform chosen';
61
63
  }
@@ -141,6 +143,33 @@ function aggregateSubtitle(node) {
141
143
  return `by ${groupBy.join(', ')}, computing nothing`;
142
144
  return `by ${groupBy.join(', ')} \u2192 ${aggregates.length} ${aggregates.length === 1 ? 'value' : 'values'}`;
143
145
  }
146
+ /**
147
+ * A lookup's face: what it matches on, and how many fields it brings across.
148
+ *
149
+ * The **key pair** is what gets the room, not the field list, and that is the
150
+ * decision. A lookup that is wrong is almost never wrong about which columns it
151
+ * wanted — it is wrong about the two columns it matches on, because those are the
152
+ * ones that have to agree between two systems that have never met. `planId =
153
+ * Plan ID` readable off the canvas is the difference between spotting that and
154
+ * opening every node in the graph.
155
+ *
156
+ * The disposition is on the face too, and only when it is not the default, for
157
+ * the reason a rename says "drops the rest": `drop` means this node also removes
158
+ * rows, which is a thing that should never require opening a box to discover.
159
+ */
160
+ function lookupSubtitle(node) {
161
+ const key = typeof node.key === 'string' ? node.key : '';
162
+ const referenceKey = typeof node.referenceKey === 'string' ? node.referenceKey : '';
163
+ if (key.length === 0 || referenceKey.length === 0)
164
+ return 'no key chosen';
165
+ const fields = Object.entries(node.fields ?? {}).filter(([from, to]) => from.length > 0 && to.length > 0);
166
+ if (fields.length === 0)
167
+ return `${key} = ${referenceKey}, no fields`;
168
+ const brings = fields.length === 1 ? `+${fields[0]?.[1]}` : `+${fields.length} fields`;
169
+ const unmatched = workflowLookupUnmatched(node);
170
+ const tail = unmatched === 'drop' ? ', drops misses' : unmatched === 'fail' ? ', fails on a miss' : '';
171
+ return `${key} = ${referenceKey} ${brings}${tail}`;
172
+ }
144
173
  /** How many comparisons a predicate is made of, groups not counted. */
145
174
  function countFilterLeaves(predicate) {
146
175
  if (predicate.kind === 'all' || predicate.kind === 'any') {
@@ -388,6 +417,8 @@ export function defaultLabel(kind) {
388
417
  return 'Rename';
389
418
  if (kind === 'aggregate')
390
419
  return 'Aggregate';
420
+ if (kind === 'lookup')
421
+ return 'Lookup';
391
422
  if (kind === 'transform')
392
423
  return 'Transform';
393
424
  return unreachableNodeKind(kind, 'defaultLabel');
@@ -18,8 +18,8 @@
18
18
  * executes it, it belongs to core; if only this screen has an opinion about it,
19
19
  * it belongs here.
20
20
  */
21
- export type { CallableWorkflowBlock, CallableWorkflowDisagreement, CallableWorkflowRef, CatalogWorkflow, CatalogWorkflowRelease, WorkflowBranchLabel, WorkflowEdge, WorkflowCallMode, WorkflowCallNode, WorkflowEnvPredicate, WorkflowFilterAll, WorkflowFilterAny, WorkflowFilterComparison, WorkflowFilterGroup, WorkflowFilterNode, WorkflowFilterOneOf, WorkflowFilterOperator, WorkflowFilterPredicate, WorkflowFilterPredicateKind, WorkflowFilterPresence, WorkflowFilterValue, WorkflowGraph, WorkflowIfNode, WorkflowIfPredicate, WorkflowAggregate, WorkflowAggregateFunction, WorkflowAggregateNode, WorkflowNode, WorkflowNodeKind, WorkflowPredicateKind, WorkflowRenameNode, WorkflowRenameUnnamed, WorkflowRowCountPredicate, WorkflowSinkNode, WorkflowSkipReason, WorkflowSourceNode, WorkflowTransformNode, } from '@dudousxd/nestjs-catalog/client';
22
- export { callableWorkflowBlock, isWorkflowBranchLabel, isWorkflowFilterOperator, isWorkflowFilterPredicate, isWorkflowFilterPredicateKind, isWorkflowFilterValue, isWorkflowNodeKind, isWorkflowPredicateKind, isWorkflowAggregateFunction, isWorkflowRenameUnnamed, aggregateRefusals, workflowAggregateColumns, workflowAggregateJoinMaxLength, workflowAggregateMaxGroups, workflowAggregateNeedsColumn, workflowAggregateOutputColumns, workflowAggregateSeparator, renameColumnRefusals, workflowKnownColumns, workflowRenameUnnamed, WORKFLOW_CALL_MODES, unreachableCallMode, workflowCallMode, unreachableFilterOperator, unreachableFilterPredicateKind, unreachableNodeKind, unreachablePredicateKind, unreachableAggregateFunction, unreachableRenameUnnamed, workflowNarrowedTypes, WORKFLOW_BRANCH_LABELS, WORKFLOW_FILTER_COLUMN_PATTERN, WORKFLOW_FILTER_MAX_DEPTH, WORKFLOW_FILTER_MAX_VALUES, WORKFLOW_FILTER_OPERATORS, WORKFLOW_FILTER_PREDICATE_KINDS, WORKFLOW_PREDICATE_KINDS, WORKFLOW_AGGREGATE_DEFAULT_SEPARATOR, WORKFLOW_AGGREGATE_FUNCTIONS, WORKFLOW_AGGREGATE_GROUPS_CEILING, WORKFLOW_AGGREGATE_JOIN_LENGTH_CEILING, WORKFLOW_AGGREGATE_JOIN_MAX_LENGTH, WORKFLOW_AGGREGATE_MAX_AGGREGATES, WORKFLOW_AGGREGATE_MAX_GROUP_BY, WORKFLOW_AGGREGATE_MAX_GROUPS, WORKFLOW_AGGREGATE_MAX_SEPARATOR, WORKFLOW_RENAME_MAX_COLUMNS, WORKFLOW_RENAME_UNNAMED, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, } from '@dudousxd/nestjs-catalog/client';
21
+ export type { CallableWorkflowBlock, CallableWorkflowDisagreement, CallableWorkflowRef, CatalogWorkflow, CatalogWorkflowRelease, WorkflowBranchLabel, WorkflowEdge, WorkflowCallMode, WorkflowCallNode, WorkflowEnvPredicate, WorkflowFilterAll, WorkflowFilterAny, WorkflowFilterComparison, WorkflowFilterGroup, WorkflowFilterNode, WorkflowFilterOneOf, WorkflowFilterOperator, WorkflowFilterPredicate, WorkflowFilterPredicateKind, WorkflowFilterPresence, WorkflowFilterValue, WorkflowGraph, WorkflowIfNode, WorkflowIfPredicate, WorkflowAggregate, WorkflowAggregateFunction, WorkflowAggregateNode, WorkflowNode, WorkflowNodeKind, WorkflowPredicateKind, WorkflowLookupNode, WorkflowLookupUnmatched, WorkflowRenameNode, WorkflowRenameUnnamed, WorkflowRowCountPredicate, WorkflowSinkNode, WorkflowSkipReason, WorkflowSourceNode, WorkflowTransformNode, } from '@dudousxd/nestjs-catalog/client';
22
+ export { callableWorkflowBlock, isWorkflowBranchLabel, isWorkflowFilterOperator, isWorkflowFilterPredicate, isWorkflowFilterPredicateKind, isWorkflowFilterValue, isWorkflowLookupFields, isWorkflowLookupUnmatched, isWorkflowNodeKind, isWorkflowPredicateKind, isWorkflowAggregateFunction, isWorkflowRenameUnnamed, aggregateRefusals, workflowAggregateColumns, workflowAggregateJoinMaxLength, workflowAggregateMaxGroups, workflowAggregateNeedsColumn, workflowAggregateOutputColumns, workflowAggregateSeparator, renameColumnRefusals, workflowKnownColumns, workflowRenameUnnamed, lookupConfigRefusals, workflowLookupColumns, workflowLookupUnmatched, WORKFLOW_CALL_MODES, unreachableCallMode, workflowCallMode, unreachableFilterOperator, unreachableFilterPredicateKind, unreachableNodeKind, unreachablePredicateKind, unreachableAggregateFunction, unreachableLookupUnmatched, unreachableRenameUnnamed, workflowNarrowedTypes, WORKFLOW_BRANCH_LABELS, WORKFLOW_FILTER_COLUMN_PATTERN, WORKFLOW_FILTER_MAX_DEPTH, WORKFLOW_FILTER_MAX_VALUES, WORKFLOW_FILTER_OPERATORS, WORKFLOW_FILTER_PREDICATE_KINDS, WORKFLOW_PREDICATE_KINDS, WORKFLOW_AGGREGATE_DEFAULT_SEPARATOR, WORKFLOW_AGGREGATE_FUNCTIONS, WORKFLOW_AGGREGATE_GROUPS_CEILING, WORKFLOW_AGGREGATE_JOIN_LENGTH_CEILING, WORKFLOW_AGGREGATE_JOIN_MAX_LENGTH, WORKFLOW_AGGREGATE_MAX_AGGREGATES, WORKFLOW_AGGREGATE_MAX_GROUP_BY, WORKFLOW_AGGREGATE_MAX_GROUPS, WORKFLOW_AGGREGATE_MAX_SEPARATOR, WORKFLOW_LOOKUP_MAX_FIELDS, WORKFLOW_LOOKUP_MAX_REFERENCE_ROWS, WORKFLOW_LOOKUP_UNMATCHED, WORKFLOW_RENAME_MAX_COLUMNS, WORKFLOW_RENAME_UNNAMED, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, } from '@dudousxd/nestjs-catalog/client';
23
23
  import { type WorkflowBranchLabel, type WorkflowNode, type WorkflowSkipReason } from '@dudousxd/nestjs-catalog/client';
24
24
  /**
25
25
  * What a caller may set.
@@ -23,7 +23,7 @@ export {
23
23
  // not a copy: the picker greys an entry out and the server reasons about the
24
24
  // same list, and two copies of that rule is a picker that eventually offers
25
25
  // something the rest of the system will not accept.
26
- callableWorkflowBlock, isWorkflowBranchLabel, isWorkflowFilterOperator, isWorkflowFilterPredicate, isWorkflowFilterPredicateKind, isWorkflowFilterValue, isWorkflowNodeKind, isWorkflowPredicateKind, isWorkflowAggregateFunction, isWorkflowRenameUnnamed,
26
+ callableWorkflowBlock, isWorkflowBranchLabel, isWorkflowFilterOperator, isWorkflowFilterPredicate, isWorkflowFilterPredicateKind, isWorkflowFilterValue, isWorkflowLookupFields, isWorkflowLookupUnmatched, isWorkflowNodeKind, isWorkflowPredicateKind, isWorkflowAggregateFunction, isWorkflowRenameUnnamed,
27
27
  // The aggregate rules, core's for the reason every rule here is core's: an
28
28
  // inspector that offered a function the fold cannot compute would save a
29
29
  // graph that fails inside a durable step, and one with its own copy of the
@@ -37,18 +37,25 @@ aggregateRefusals, workflowAggregateColumns, workflowAggregateJoinMaxLength, wor
37
37
  // is what lets the inspector say which columns actually reach a node instead of
38
38
  // guessing.
39
39
  renameColumnRefusals, workflowKnownColumns, workflowRenameUnnamed,
40
+ // The lookup rules, core's for the same reason. `workflowLookupColumns` is the
41
+ // one that earns its place on this screen: a lookup is the only node whose two
42
+ // inputs are not interchangeable, so an inspector that worked out for itself
43
+ // which columns are on which side would eventually offer a key column that only
44
+ // exists on the reference — a join that matches nothing, which is the failure
45
+ // the node was built to end.
46
+ lookupConfigRefusals, workflowLookupColumns, workflowLookupUnmatched,
40
47
  // The two wire formats a call node can be authored in, plus the reader that
41
48
  // applies the default. Core's, not a copy, for the reason every rule here is:
42
49
  // an inspector offering a mode the runner cannot build a payload for is a
43
50
  // graph somebody saves and a child run that fails, and a screen carrying its
44
51
  // own `?? 'envelope'` would eventually disagree with `workflowGraphHash` and
45
52
  // show unsaved changes on a graph nobody edited.
46
- WORKFLOW_CALL_MODES, unreachableCallMode, workflowCallMode, unreachableFilterOperator, unreachableFilterPredicateKind, unreachableNodeKind, unreachablePredicateKind, unreachableAggregateFunction, unreachableRenameUnnamed,
53
+ WORKFLOW_CALL_MODES, unreachableCallMode, workflowCallMode, unreachableFilterOperator, unreachableFilterPredicateKind, unreachableNodeKind, unreachablePredicateKind, unreachableAggregateFunction, unreachableLookupUnmatched, unreachableRenameUnnamed,
47
54
  // Core's, not a copy, for the reason every other rule here is core's: the
48
55
  // inspector has to offer exactly the acknowledgements `validateWorkflow`
49
56
  // requires, and a screen that worked out its own list would offer a set the
50
57
  // server then refuses — with the person having ticked a box to be told no.
51
- workflowNarrowedTypes, WORKFLOW_BRANCH_LABELS, WORKFLOW_FILTER_COLUMN_PATTERN, WORKFLOW_FILTER_MAX_DEPTH, WORKFLOW_FILTER_MAX_VALUES, WORKFLOW_FILTER_OPERATORS, WORKFLOW_FILTER_PREDICATE_KINDS, WORKFLOW_PREDICATE_KINDS, WORKFLOW_AGGREGATE_DEFAULT_SEPARATOR, WORKFLOW_AGGREGATE_FUNCTIONS, WORKFLOW_AGGREGATE_GROUPS_CEILING, WORKFLOW_AGGREGATE_JOIN_LENGTH_CEILING, WORKFLOW_AGGREGATE_JOIN_MAX_LENGTH, WORKFLOW_AGGREGATE_MAX_AGGREGATES, WORKFLOW_AGGREGATE_MAX_GROUP_BY, WORKFLOW_AGGREGATE_MAX_GROUPS, WORKFLOW_AGGREGATE_MAX_SEPARATOR, WORKFLOW_RENAME_MAX_COLUMNS, WORKFLOW_RENAME_UNNAMED, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, } from '@dudousxd/nestjs-catalog/client';
58
+ workflowNarrowedTypes, WORKFLOW_BRANCH_LABELS, WORKFLOW_FILTER_COLUMN_PATTERN, WORKFLOW_FILTER_MAX_DEPTH, WORKFLOW_FILTER_MAX_VALUES, WORKFLOW_FILTER_OPERATORS, WORKFLOW_FILTER_PREDICATE_KINDS, WORKFLOW_PREDICATE_KINDS, WORKFLOW_AGGREGATE_DEFAULT_SEPARATOR, WORKFLOW_AGGREGATE_FUNCTIONS, WORKFLOW_AGGREGATE_GROUPS_CEILING, WORKFLOW_AGGREGATE_JOIN_LENGTH_CEILING, WORKFLOW_AGGREGATE_JOIN_MAX_LENGTH, WORKFLOW_AGGREGATE_MAX_AGGREGATES, WORKFLOW_AGGREGATE_MAX_GROUP_BY, WORKFLOW_AGGREGATE_MAX_GROUPS, WORKFLOW_AGGREGATE_MAX_SEPARATOR, WORKFLOW_LOOKUP_MAX_FIELDS, WORKFLOW_LOOKUP_MAX_REFERENCE_ROWS, WORKFLOW_LOOKUP_UNMATCHED, WORKFLOW_RENAME_MAX_COLUMNS, WORKFLOW_RENAME_UNNAMED, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, } from '@dudousxd/nestjs-catalog/client';
52
59
  import { WORKFLOW_NODE_ID_PATTERN, } from '@dudousxd/nestjs-catalog/client';
53
60
  export function describeDurability(durability) {
54
61
  if (!durability) {
@@ -1,6 +1,6 @@
1
1
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { Handle, Position } from '@xyflow/react';
3
- import { CircleAlert, CircleCheck, CircleSlash, Code2, Database, ExternalLink, Filter, GitBranch, Loader2, Plug, Repeat, Sigma, TextCursorInput, TriangleAlert, } from 'lucide-react';
3
+ import { CircleAlert, CircleCheck, CircleSlash, Code2, Combine, Database, ExternalLink, Filter, GitBranch, Loader2, Plug, Repeat, Sigma, TextCursorInput, TriangleAlert, } from 'lucide-react';
4
4
  import { motion, useReducedMotion } from 'motion/react';
5
5
  import { createContext, useContext, } from 'react';
6
6
  import { cn } from '../cn';
@@ -124,6 +124,19 @@ const KIND_STYLE = {
124
124
  icon: Sigma,
125
125
  noun: 'aggregate',
126
126
  },
127
+ // Indigo and a mark of two things becoming one. A lookup is the only node with
128
+ // *two kinds of input* — one it holds and one it streams — and the whole way it
129
+ // goes wrong is somebody reading it as another step in the line and not noticing
130
+ // which wire is which. Deliberately not the sky a source wears, even though the
131
+ // reference edge usually comes straight off one: the point of the colour is that
132
+ // this box is where two lines meet, not where one starts.
133
+ lookup: {
134
+ accent: 'bg-gradient-to-b from-indigo-400 to-indigo-600',
135
+ chip: 'text-indigo-700 dark:text-indigo-300',
136
+ wash: 'bg-indigo-50/70 dark:bg-indigo-950/30',
137
+ icon: Combine,
138
+ noun: 'lookup',
139
+ },
127
140
  };
128
141
  /**
129
142
  * Handles are styled larger than React Flow's default 6px dot.
@@ -123,6 +123,17 @@ const NODE_FACTORIES = {
123
123
  // does not error — it commits a plausible number. A prefilled aggregate would
124
124
  // be a summary of somebody else's data, shipped with an air of authority.
125
125
  aggregate: (id, name, init) => ({ id, name, kind: 'aggregate', ...init }),
126
+ // `lookup` arrived sixth, and the map stopped the build a sixth time.
127
+ //
128
+ // Unused by every template below, and the reason is not the one the five above
129
+ // give. A lookup's content is not only facts about somebody's data — it is a
130
+ // `reference` that names *a node id in the graph being built*, so a template
131
+ // that prefilled one would be writing down the id of a node it also has to
132
+ // create, in an order nothing enforces. When that goes wrong the graph does not
133
+ // fail to save: `validateWorkflow` refuses it, which is the good case, and the
134
+ // bad case is a template that happens to name a node that exists and quietly
135
+ // holds the wrong side of the join in memory.
136
+ lookup: (id, name, init) => ({ id, name, kind: 'lookup', ...init }),
126
137
  };
127
138
  /* -------------------------------------------------------------------------- */
128
139
  /* Starter transform code */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dudousxd/nestjs-catalog-react",
3
- "version": "0.31.0",
3
+ "version": "0.33.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.27.0"
113
+ "@dudousxd/nestjs-catalog": "0.30.0"
114
114
  },
115
115
  "dependencies": {
116
116
  "clsx": "2.1.1",