@dudousxd/nestjs-catalog-react 0.16.0 → 0.18.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.
Files changed (52) hide show
  1. package/README.md +39 -13
  2. package/dist/ConnectionPanel.d.ts +11 -7
  3. package/dist/ConnectionPanel.js +65 -28
  4. package/dist/ObjectExplorer.js +424 -48
  5. package/dist/PipelineConsole.d.ts +23 -126
  6. package/dist/PipelineConsole.js +39 -551
  7. package/dist/QueryConsole.js +25 -17
  8. package/dist/SavedQueryPanel.js +1 -1
  9. package/dist/TransformEditor.js +12 -3
  10. package/dist/WorkflowCanvas.js +401 -29
  11. package/dist/bundler/index.d.ts +20 -0
  12. package/dist/bundler/index.js +20 -0
  13. package/dist/bundler/shiki-subset.d.ts +83 -0
  14. package/dist/bundler/shiki-subset.js +196 -0
  15. package/dist/context.d.ts +181 -38
  16. package/dist/context.js +44 -11
  17. package/dist/diff/RevisionDiff.d.ts +67 -4
  18. package/dist/diff/RevisionDiff.js +126 -91
  19. package/dist/index.d.ts +8 -5
  20. package/dist/index.js +56 -20
  21. package/dist/routes.d.ts +54 -13
  22. package/dist/routes.js +5 -4
  23. package/dist/schema-discovery.d.ts +216 -0
  24. package/dist/schema-discovery.js +225 -0
  25. package/dist/source-fields.d.ts +1 -12
  26. package/dist/source-fields.js +13 -16
  27. package/dist/ui/code-editor.d.ts +196 -8
  28. package/dist/ui/code-editor.js +184 -72
  29. package/dist/ui/code-languages.d.ts +80 -0
  30. package/dist/ui/code-languages.js +76 -0
  31. package/dist/ui/code-theme.d.ts +25 -0
  32. package/dist/ui/code-theme.js +26 -0
  33. package/dist/ui/dialog.d.ts +13 -1
  34. package/dist/ui/dialog.js +13 -2
  35. package/dist/workflow/graph.js +31 -9
  36. package/dist/workflow/index.d.ts +2 -0
  37. package/dist/workflow/index.js +7 -0
  38. package/dist/workflow/lifecycle.d.ts +164 -0
  39. package/dist/workflow/lifecycle.js +249 -0
  40. package/dist/workflow/model.d.ts +1 -1
  41. package/dist/workflow/nodes.js +10 -1
  42. package/dist/workflow/runs.d.ts +38 -0
  43. package/dist/workflow/runs.js +101 -0
  44. package/dist/workflow/shape.d.ts +169 -0
  45. package/dist/workflow/shape.js +249 -0
  46. package/dist/workflow/templates.d.ts +623 -0
  47. package/dist/workflow/templates.js +1092 -0
  48. package/dist/workflow/validate.d.ts +20 -1
  49. package/dist/workflow/validate.js +41 -3
  50. package/package.json +21 -17
  51. package/dist/diff/line-diff.d.ts +0 -124
  52. package/dist/diff/line-diff.js +0 -318
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Build-time entry point: things a host's bundler config imports, not its app.
3
+ *
4
+ * Kept off the package's main entry deliberately. Everything reachable from
5
+ * `index.ts` is resolved and bundled by the host whether or not it renders it,
6
+ * and a build plugin has no business in a browser graph — the same reason
7
+ * `WorkflowCanvas` and the chart renderers sit on their own subpaths.
8
+ *
9
+ * import { shikiSubset } from "@dudousxd/nestjs-catalog-react/bundler";
10
+ *
11
+ * The `.js` on the specifiers below is the one thing that differs from every
12
+ * other file in this package, and it is not style. Everywhere else the importer
13
+ * is a bundler, which resolves an extensionless path; here it is NODE, because
14
+ * Vite loads `vite.config.ts` by bundling it and then importing the result, and
15
+ * an external dependency of that config is resolved by Node's ESM rules — which
16
+ * do not guess extensions. Without these this subpath throws ERR_MODULE_NOT_FOUND
17
+ * inside the config file, before a single line of the build runs.
18
+ */
19
+ export { shikiSubset, type ShikiSubsetPlugin } from './shiki-subset.js';
20
+ export { CATALOG_CODE_LANGUAGES, CATALOG_CODE_THEMES, type CatalogCodeLanguage, type CatalogCodeTheme, } from '../ui/code-languages.js';
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Build-time entry point: things a host's bundler config imports, not its app.
3
+ *
4
+ * Kept off the package's main entry deliberately. Everything reachable from
5
+ * `index.ts` is resolved and bundled by the host whether or not it renders it,
6
+ * and a build plugin has no business in a browser graph — the same reason
7
+ * `WorkflowCanvas` and the chart renderers sit on their own subpaths.
8
+ *
9
+ * import { shikiSubset } from "@dudousxd/nestjs-catalog-react/bundler";
10
+ *
11
+ * The `.js` on the specifiers below is the one thing that differs from every
12
+ * other file in this package, and it is not style. Everywhere else the importer
13
+ * is a bundler, which resolves an extensionless path; here it is NODE, because
14
+ * Vite loads `vite.config.ts` by bundling it and then importing the result, and
15
+ * an external dependency of that config is resolved by Node's ESM rules — which
16
+ * do not guess extensions. Without these this subpath throws ERR_MODULE_NOT_FOUND
17
+ * inside the config file, before a single line of the build runs.
18
+ */
19
+ export { shikiSubset } from './shiki-subset.js';
20
+ export { CATALOG_CODE_LANGUAGES, CATALOG_CODE_THEMES, } from '../ui/code-languages.js';
@@ -0,0 +1,83 @@
1
+ /**
2
+ * A Vite/Rollup plugin that prunes Shiki down to what this console renders.
3
+ *
4
+ * THE PROBLEM IT SOLVES
5
+ * ---------------------
6
+ * `@pierre/diffs` is the editor and the diff, and it resolves a grammar by
7
+ * looking the name up in Shiki's `bundledLanguages` — an object of ~240 entries
8
+ * whose values are `() => import('@shikijs/langs/<name>')`. Themes work the same
9
+ * way through `@pierre/theming`'s collections. A bundler cannot tree-shake a
10
+ * dynamic import selected by a runtime key, so it emits a chunk for every entry
11
+ * whether or not the application can ever reach it. Measured on
12
+ * `packages/dashboard`'s SPA before this plugin existed: 319 JS chunks, of which
13
+ * 242 were grammars (7.47 MB minified) and 75 were themes (1.58 MB) — against a
14
+ * console that renders SQL, JSON, TSX and Python in two Pierre palettes.
15
+ *
16
+ * WHAT IT IS NOT
17
+ * --------------
18
+ * It is NOT an entry-bundle saving, and claiming one would be a lie the first
19
+ * `ls dist/spa/assets` would catch. Every one of those chunks is lazy: Shiki's
20
+ * core, its JavaScript regex engine and the editor itself are in the entry, and
21
+ * they stay there. What this removes is emitted-but-unreachable bytes and the
22
+ * files carrying them.
23
+ *
24
+ * HOW IT WORKS, AND WHY REWRITING IS THE SOUND WAY
25
+ * ------------------------------------------------
26
+ * Every `import('<registry>/<name>')` for a name outside the subset is rewritten
27
+ * to a rejected promise. Nothing else changes: the registry keeps its key, the
28
+ * loader is still a function, and the arrow is still only called if something
29
+ * asks for that name — at which point it rejects with a message naming the
30
+ * specifier and this plugin. There is no chunk because there is no longer an
31
+ * `import()` for Rollup to split on.
32
+ *
33
+ * The alternative — resolving those specifiers to a stub module — was rejected:
34
+ * a stub is still a module, so Rollup still emits ~240 chunks, only tiny ones.
35
+ * Deleting the entries from the registry object instead would mean rewriting
36
+ * generated dependency source by shape rather than by specifier, and a
37
+ * specifier is a package's public API where its bundler output is not.
38
+ *
39
+ * WHY IT CANNOT GO QUIET
40
+ * ----------------------
41
+ * A pruner that stops matching prunes nothing and says nothing — the build gets
42
+ * slower and fatter and stays green. So {@link buildEnd} asserts the opposite of
43
+ * the usual thing: not that names were REMOVED, but that every name that was
44
+ * KEPT was actually there to keep, and that each registry was seen at all. A
45
+ * Shiki release that renames `tsx`, a typo in `CATALOG_CODE_LANGUAGES`, a
46
+ * `@pierre/theming` that stops naming its palettes as subpath imports — each
47
+ * one fails the build with the name it could not find.
48
+ *
49
+ * USAGE
50
+ * -----
51
+ * ```ts
52
+ * import { shikiSubset } from '@dudousxd/nestjs-catalog-react/bundler';
53
+ *
54
+ * export default defineConfig({ plugins: [react(), shikiSubset()] });
55
+ * ```
56
+ *
57
+ * A host that wants a grammar this console does not — its own `<CodeEditor>` on
58
+ * its own page — should not install this plugin, because the subset is this
59
+ * package's set and not theirs. There is no option to extend it, deliberately:
60
+ * an extensible allow-list is a list again, and the type that makes this one
61
+ * safe is not extensible either.
62
+ */
63
+ export declare function shikiSubset(): ShikiSubsetPlugin;
64
+ /** The name each pruned `import()` is rewritten to call. */
65
+ export declare const PRUNED = "__catalogPrunedShikiImport";
66
+ /**
67
+ * The plugin, typed structurally.
68
+ *
69
+ * Written out rather than imported from `vite` or `rollup`, because this package
70
+ * ships React components and taking a build tool as a dependency to name one
71
+ * interface would put it in every consumer's install. Vite accepts any object of
72
+ * this shape; the five fields are the five it reads.
73
+ */
74
+ export interface ShikiSubsetPlugin {
75
+ name: string;
76
+ enforce: 'pre';
77
+ apply: 'build';
78
+ transform(code: string): {
79
+ code: string;
80
+ map: null;
81
+ } | null;
82
+ buildEnd(error?: unknown): void;
83
+ }
@@ -0,0 +1,196 @@
1
+ // `.js` on the specifier, because NODE resolves this one and does not guess
2
+ // extensions — see `bundler/index.ts` for why the importer is Node here.
3
+ import { CATALOG_CODE_LANGUAGES, CATALOG_CODE_THEMES, } from '../ui/code-languages.js';
4
+ /**
5
+ * A Vite/Rollup plugin that prunes Shiki down to what this console renders.
6
+ *
7
+ * THE PROBLEM IT SOLVES
8
+ * ---------------------
9
+ * `@pierre/diffs` is the editor and the diff, and it resolves a grammar by
10
+ * looking the name up in Shiki's `bundledLanguages` — an object of ~240 entries
11
+ * whose values are `() => import('@shikijs/langs/<name>')`. Themes work the same
12
+ * way through `@pierre/theming`'s collections. A bundler cannot tree-shake a
13
+ * dynamic import selected by a runtime key, so it emits a chunk for every entry
14
+ * whether or not the application can ever reach it. Measured on
15
+ * `packages/dashboard`'s SPA before this plugin existed: 319 JS chunks, of which
16
+ * 242 were grammars (7.47 MB minified) and 75 were themes (1.58 MB) — against a
17
+ * console that renders SQL, JSON, TSX and Python in two Pierre palettes.
18
+ *
19
+ * WHAT IT IS NOT
20
+ * --------------
21
+ * It is NOT an entry-bundle saving, and claiming one would be a lie the first
22
+ * `ls dist/spa/assets` would catch. Every one of those chunks is lazy: Shiki's
23
+ * core, its JavaScript regex engine and the editor itself are in the entry, and
24
+ * they stay there. What this removes is emitted-but-unreachable bytes and the
25
+ * files carrying them.
26
+ *
27
+ * HOW IT WORKS, AND WHY REWRITING IS THE SOUND WAY
28
+ * ------------------------------------------------
29
+ * Every `import('<registry>/<name>')` for a name outside the subset is rewritten
30
+ * to a rejected promise. Nothing else changes: the registry keeps its key, the
31
+ * loader is still a function, and the arrow is still only called if something
32
+ * asks for that name — at which point it rejects with a message naming the
33
+ * specifier and this plugin. There is no chunk because there is no longer an
34
+ * `import()` for Rollup to split on.
35
+ *
36
+ * The alternative — resolving those specifiers to a stub module — was rejected:
37
+ * a stub is still a module, so Rollup still emits ~240 chunks, only tiny ones.
38
+ * Deleting the entries from the registry object instead would mean rewriting
39
+ * generated dependency source by shape rather than by specifier, and a
40
+ * specifier is a package's public API where its bundler output is not.
41
+ *
42
+ * WHY IT CANNOT GO QUIET
43
+ * ----------------------
44
+ * A pruner that stops matching prunes nothing and says nothing — the build gets
45
+ * slower and fatter and stays green. So {@link buildEnd} asserts the opposite of
46
+ * the usual thing: not that names were REMOVED, but that every name that was
47
+ * KEPT was actually there to keep, and that each registry was seen at all. A
48
+ * Shiki release that renames `tsx`, a typo in `CATALOG_CODE_LANGUAGES`, a
49
+ * `@pierre/theming` that stops naming its palettes as subpath imports — each
50
+ * one fails the build with the name it could not find.
51
+ *
52
+ * USAGE
53
+ * -----
54
+ * ```ts
55
+ * import { shikiSubset } from '@dudousxd/nestjs-catalog-react/bundler';
56
+ *
57
+ * export default defineConfig({ plugins: [react(), shikiSubset()] });
58
+ * ```
59
+ *
60
+ * A host that wants a grammar this console does not — its own `<CodeEditor>` on
61
+ * its own page — should not install this plugin, because the subset is this
62
+ * package's set and not theirs. There is no option to extend it, deliberately:
63
+ * an extensible allow-list is a list again, and the type that makes this one
64
+ * safe is not extensible either.
65
+ */
66
+ export function shikiSubset() {
67
+ const registries = REGISTRIES.map((registry) => ({
68
+ ...registry,
69
+ /** Which of `keep` this build actually found. The absentees fail the build. */
70
+ found: new Set(),
71
+ /** Whether the registry was in the module graph at all. */
72
+ seen: false,
73
+ }));
74
+ return {
75
+ name: 'catalog-shiki-subset',
76
+ // Before anything else rewrites a dynamic import — this reads the
77
+ // dependency's own source, and wants it as the dependency wrote it.
78
+ enforce: 'pre',
79
+ // Build only. A dev server pre-bundles dependencies with esbuild, so this
80
+ // hook would see a fraction of them and `buildEnd` would fail the run over
81
+ // an absence that means nothing. Dev pays a slower cold start; nothing
82
+ // about correctness differs, because a pruned grammar is one nothing asks
83
+ // for.
84
+ apply: 'build',
85
+ transform(code) {
86
+ if (!registries.some((registry) => code.includes(registry.prefix)))
87
+ return null;
88
+ let touched = false;
89
+ const next = code.replace(DYNAMIC_IMPORT, (match, _quote, specifier) => {
90
+ const registry = registries.find((candidate) => specifier.startsWith(candidate.prefix));
91
+ if (!registry)
92
+ return match;
93
+ registry.seen = true;
94
+ const name = specifier.slice(registry.prefix.length);
95
+ if (registry.keep.has(name)) {
96
+ registry.found.add(name);
97
+ return match;
98
+ }
99
+ touched = true;
100
+ return `${PRUNED}(${JSON.stringify(specifier)})`;
101
+ });
102
+ // `null` when nothing changed, so a module that merely MENTIONS a registry
103
+ // — the resolver that reads it, say — is handed back untouched rather than
104
+ // re-emitted with a sourcemap this plugin cannot honestly produce.
105
+ return touched ? { code: `${prunedHelper()}\n${next}`, map: null } : null;
106
+ },
107
+ buildEnd(error) {
108
+ // A failed build has already said what is wrong, and the registries it
109
+ // never reached would only add noise on top of the real error.
110
+ if (error)
111
+ return;
112
+ const complaints = [];
113
+ for (const registry of registries) {
114
+ if (!registry.seen) {
115
+ complaints.push(`no \`import('${registry.prefix}…')\` reached this plugin, so nothing was pruned from it`);
116
+ continue;
117
+ }
118
+ const missing = [...registry.keep].filter((name) => !registry.found.has(name));
119
+ if (missing.length > 0) {
120
+ complaints.push(`${registry.prefix} offers no ${registry.what} named ${missing.join(', ')}`);
121
+ }
122
+ }
123
+ if (complaints.length > 0) {
124
+ throw new Error(`catalog-shiki-subset: ${complaints.join('; ')}. ${ADVICE}`);
125
+ }
126
+ },
127
+ };
128
+ }
129
+ /**
130
+ * Every dynamic import, by the only part of it that is a public contract.
131
+ *
132
+ * A package's subpath exports are declared in its `package.json` and are what a
133
+ * caller is allowed to write; the file its bundler emitted them into is not.
134
+ * So this matches `import('…')` and reads the specifier, rather than matching
135
+ * the `(() => import(…))` wrapper Shiki's generator happens to produce and
136
+ * `@pierre/theming`'s does not.
137
+ */
138
+ const DYNAMIC_IMPORT = /\bimport\(\s*(['"])([^'"]+)\1\s*\)/g;
139
+ /** What to do about it, which is the same answer whichever way the subset went wrong. */
140
+ const ADVICE = 'The subset in `ui/code-languages.ts` is out of step with the packages it prunes — left alone ' +
141
+ 'this plugin would silently stop pruning, or prune a grammar the console renders. Fix the ' +
142
+ 'names, or drop the plugin.';
143
+ /** The registries pruned, and what survives each. */
144
+ const REGISTRIES = [
145
+ {
146
+ prefix: '@shikijs/langs/',
147
+ what: 'grammar',
148
+ keep: new Set(CATALOG_CODE_LANGUAGES),
149
+ },
150
+ {
151
+ // Every one. The console is painted by Pierre's palettes below, and Shiki's
152
+ // own 65 are reachable only by naming one, which nothing here does.
153
+ prefix: '@shikijs/themes/',
154
+ what: 'theme',
155
+ keep: new Set(),
156
+ },
157
+ {
158
+ prefix: '@pierre/theme/',
159
+ what: 'theme',
160
+ keep: new Set(CATALOG_CODE_THEMES),
161
+ },
162
+ ];
163
+ /** The name each pruned `import()` is rewritten to call. */
164
+ export const PRUNED = '__catalogPrunedShikiImport';
165
+ /**
166
+ * What a pruned name evaluates to, declared ONCE per rewritten module.
167
+ *
168
+ * A rejected promise rather than a throw, because the registry's value is a
169
+ * loader that both `@pierre/diffs` and `@pierre/theming` `await` — so a
170
+ * rejection surfaces where the caller already handles one, while a synchronous
171
+ * throw from inside an arrow would surface somewhere neither of them looks.
172
+ * Nothing is constructed until the loader is called, so there is no promise
173
+ * sitting around to go unhandled.
174
+ *
175
+ * A shared helper rather than the sentence inlined at each of the ~320 call
176
+ * sites, and that is measured rather than tidy: inlined, the message added
177
+ * 58 KB to `packages/dashboard`'s ENTRY chunk — the one chunk this change was
178
+ * not supposed to touch — because the registry object it lives in is in the
179
+ * entry path even when every grammar it names is not. Hoisted, the call sites
180
+ * are shorter than the `import()` they replace once the minifier has renamed
181
+ * the helper, and the entry comes out smaller than before.
182
+ *
183
+ * The specifier is passed because the type that normally catches this
184
+ * (`CatalogCodeLanguage`) only sees literals written in this package; a `lang`
185
+ * inferred from a filename at runtime is the case that gets here, and "which
186
+ * one" is the whole question then.
187
+ *
188
+ * A function DECLARATION, so hoisting makes it valid above the registry no
189
+ * matter where in the module the imports sat.
190
+ */
191
+ function prunedHelper() {
192
+ const advice = ' was pruned from this bundle by catalog-shiki-subset. Add it to ' +
193
+ 'CATALOG_CODE_LANGUAGES / CATALOG_CODE_THEMES in @dudousxd/nestjs-catalog-react, ' +
194
+ 'or stop asking for it.';
195
+ return `function ${PRUNED}(specifier){return Promise.reject(new Error(specifier+${JSON.stringify(advice)}))}`;
196
+ }
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, DeleteReconciliation, LoadExpectation, LoadExpectationInput, ObjectQueryParams, PropertyPatch, ResolvedLoadExpectation, RowCountBound, SaveQueryInput, SavedQuery, StoredLoadExpectation, 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, SnapshotRef, 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';
@@ -116,21 +116,6 @@ export interface ConnectionInput {
116
116
  config: Record<string, unknown>;
117
117
  secretEnvVar?: string;
118
118
  }
119
- /** Same rule as {@link ConnectionInput}: authored fields only, never state. */
120
- export interface ConnectorInput {
121
- id?: string;
122
- name: string;
123
- description?: string;
124
- kind: CatalogConnector['kind'];
125
- targetType: string;
126
- config: Record<string, unknown>;
127
- connectionId?: string;
128
- secretEnvVar?: string;
129
- transformId?: string;
130
- schedule?: string;
131
- mode?: 'full' | 'incremental';
132
- enabled: boolean;
133
- }
134
119
  export interface TransformInput {
135
120
  id?: string;
136
121
  name: string;
@@ -138,6 +123,58 @@ export interface TransformInput {
138
123
  language: TransformLanguage;
139
124
  code: string;
140
125
  }
126
+ /**
127
+ * One pipeline that would break if a connection were deleted.
128
+ *
129
+ * A workflow rather than a connector, because that is the object somebody
130
+ * recognises. `through` is the server's sentence about WHICH source reaches it
131
+ * — `"Warehouse"`, or `"Warehouse" via connector abc` — so a refusal can point
132
+ * at a box on a canvas rather than at a row in a table nobody can see.
133
+ */
134
+ export interface ConnectionUse {
135
+ id: string;
136
+ name: string;
137
+ status: CatalogWorkflow['status'];
138
+ through: string;
139
+ }
140
+ /**
141
+ * What a manual run may say about itself.
142
+ *
143
+ * Both fields are absent on the run the Run button sends, and both exist for
144
+ * the case where somebody is re-driving a load they already know something
145
+ * about. See {@link CatalogClient.runWorkflow} for why `expectShrink` had to
146
+ * survive the removal of the connector run route.
147
+ */
148
+ export interface WorkflowRunOptions {
149
+ /** Re-drive under an identity that already exists, rather than minting one. */
150
+ snapshotId?: string;
151
+ /**
152
+ * Why this load is expected to lose rows, in a sentence.
153
+ *
154
+ * Sent only when somebody wrote one. The distinction between absent and
155
+ * present-but-empty is real and is the server's: absent means nobody said
156
+ * anything and the bound decides; empty means somebody claimed an
157
+ * acknowledgement and gave no reason, which is refused.
158
+ */
159
+ expectShrink?: string;
160
+ }
161
+ export interface WorkflowScheduleInput {
162
+ /** Cron-ish, interpreted by whatever schedules it. Empty means manual only. */
163
+ schedule?: string;
164
+ enabled?: boolean;
165
+ }
166
+ /**
167
+ * The stored graph, plus what the server thinks of the schedule on it.
168
+ *
169
+ * `warning` is `null` when the schedule will fire. It is a string when it will
170
+ * not — and that is the entire reason this call answers with more than the
171
+ * workflow: a cron stored on a draft, on a disabled graph, or in a syntax
172
+ * nothing can parse is a pipeline that looks scheduled and never runs, which is
173
+ * a failure with an incident behind it rather than a hypothetical.
174
+ */
175
+ export interface ScheduledWorkflow extends CatalogWorkflow {
176
+ warning?: string | null;
177
+ }
141
178
  /**
142
179
  * One saved version of the two things in this catalog whose text a person edits.
143
180
  *
@@ -257,6 +294,17 @@ export interface PersonUpsertResult {
257
294
  export interface CatalogClient {
258
295
  snapshot(): Promise<CatalogSnapshot>;
259
296
  objects(type: string, params: ObjectQueryParams): Promise<CatalogObjectPage>;
297
+ /**
298
+ * Every load of one type, newest first. Empty on a store that keeps no
299
+ * history, which is what makes the snapshot picker able to hide itself rather
300
+ * than offer a control that cannot work.
301
+ *
302
+ * A separate call from {@link objects} rather than a field on the page: the
303
+ * list changes once a load, and the page is refetched on every keystroke,
304
+ * every sort and every page turn. Carried on the page it would be a query per
305
+ * one of those.
306
+ */
307
+ snapshots(type: string): Promise<SnapshotRef[]>;
260
308
  patchType(name: string, patch: TypePatch): Promise<unknown>;
261
309
  patchProperty(name: string, property: string, patch: PropertyPatch): Promise<unknown>;
262
310
  reset(): Promise<CatalogSnapshot>;
@@ -396,27 +444,40 @@ export interface CatalogClient {
396
444
  * system it names.
397
445
  */
398
446
  checkConnection(id: string): Promise<ConnectionCheck>;
399
- /** Which connectors read through it. Named, so a refusal can say which. */
400
- connectionConnectors(id: string): Promise<CatalogConnector[]>;
447
+ /**
448
+ * Which pipelines read through it. Named, so a refusal can say which.
449
+ *
450
+ * Workflows and not connectors, because that is the question somebody is
451
+ * actually asking before they delete a connection: what breaks. A connector
452
+ * is an implementation detail of a published graph and naming one in a
453
+ * refusal would send the reader looking for a screen that no longer exists.
454
+ *
455
+ * The server's answer, and it outranks anything a screen derives from the
456
+ * workflow list: a source node may reach a connection through a connector it
457
+ * names in `config.connectorId` rather than through its own `connectionId`,
458
+ * and only the server folds both in.
459
+ */
460
+ connectionWorkflows(id: string): Promise<ConnectionUse[]>;
401
461
  deleteConnection(id: string): Promise<{
402
462
  deleted: boolean;
403
463
  }>;
404
- listConnectors(): Promise<CatalogConnector[]>;
405
- saveConnector(input: ConnectorInput): Promise<CatalogConnector>;
406
- deleteConnector(id: string): Promise<{
407
- deleted: boolean;
408
- }>;
409
- runConnector(id: string): Promise<ConnectorRun>;
410
464
  /**
411
- * What the source behind a connector looks like right now. Writes nothing.
412
- *
413
- * Typed loosely on purpose. The shape comes from
414
- * `@dudousxd/nestjs-catalog-pipeline`, and this package must not import that
415
- * one — it would drag a package built for a Node process, with database
416
- * drivers behind optional imports, into a browser bundle. `PipelineCapabilities`
417
- * above is mirrored for exactly the same reason.
465
+ * The connectors, read-only.
466
+ *
467
+ * **There is deliberately no `saveConnector`, `deleteConnector` or
468
+ * `runConnector` on this client, because there are no such routes.** A
469
+ * connector is what a published workflow runs as: `publishWorkflow` mints
470
+ * one, `deleteWorkflow` takes it away, and `runWorkflow` is the only way to
471
+ * start one. A method here that posted to `pipeline/connectors` would 404,
472
+ * and one that quietly did nothing would be worse.
473
+ *
474
+ * This read stays because it answers what a graph cannot answer about itself:
475
+ * which id the run history and the incremental watermark are keyed on, and —
476
+ * on a deployment upgraded rather than built fresh — which rows have not been
477
+ * adopted into a workflow yet. `CatalogConnector.workflowId` is what joins one
478
+ * to the graph that runs it.
418
479
  */
419
- discoverConnectorSchema(id: string): Promise<unknown>;
480
+ listConnectors(): Promise<CatalogConnector[]>;
420
481
  /**
421
482
  * Publish an object type's schema — create it, or update the shape of one
422
483
  * that exists.
@@ -494,6 +555,29 @@ export interface CatalogClient {
494
555
  */
495
556
  listWorkflows(): Promise<CatalogWorkflow[]>;
496
557
  saveWorkflow(input: WorkflowInput): Promise<CatalogWorkflow>;
558
+ /**
559
+ * Declare it finished, and mint the connector it runs as.
560
+ *
561
+ * Its own call rather than a field on the save, because publishing is a claim
562
+ * the server checks and a failed check owes an explanation naming the nodes —
563
+ * which an autosave has nowhere to put. A draft saves without validating;
564
+ * this is where the rules are answered for real.
565
+ */
566
+ publishWorkflow(id: string): Promise<CatalogWorkflow>;
567
+ /**
568
+ * Back to draft. Disables the connector, keeping its id, its run history and
569
+ * its watermark, so re-publishing resumes the same pipeline rather than
570
+ * starting a second one beside it.
571
+ */
572
+ unpublishWorkflow(id: string): Promise<CatalogWorkflow>;
573
+ /**
574
+ * Delete it, and the connector with it.
575
+ *
576
+ * The run history goes too, which is why the console asks first. It used to
577
+ * be refused while a connector still ran the graph; that check would now
578
+ * refuse every delete there is, since a published graph runs as exactly one
579
+ * connector — its own.
580
+ */
497
581
  deleteWorkflow(id: string): Promise<{
498
582
  deleted: boolean;
499
583
  }>;
@@ -501,8 +585,54 @@ export interface CatalogClient {
501
585
  * Execute it. When a durable engine is available each node runs as its own
502
586
  * step, so a failure part-way resumes rather than restarts — see
503
587
  * `PipelineCapabilities.durable`, which is what the screen states.
588
+ *
589
+ * `expectShrink` is the escape hatch for a load the row-count bound refused,
590
+ * and it reaches the server **only through here** — `POST connectors/:id/run`
591
+ * carried it and that route is gone. Without it an operator's only recourse
592
+ * would be raising `rowCount.maxShrink` in the type's policy, which stands the
593
+ * guard down for every future load of that type instead of for one snapshot.
594
+ *
595
+ * It is a reason, not a flag: the string is written into the snapshot's
596
+ * `_expectShrink` label and is the only answer anybody will have in six
597
+ * months to "why was this load allowed to lose most of the data?". Sending it
598
+ * empty is refused with a 400 asking for one, which is why the console's
599
+ * dialog will not submit a blank box rather than sending it and hoping.
600
+ */
601
+ runWorkflow(id: string, options?: WorkflowRunOptions): Promise<WorkflowRun>;
602
+ /**
603
+ * Set when this graph runs, and whether it runs at all.
604
+ *
605
+ * Both fields are optional and an absent one means "leave it alone", so a
606
+ * screen rendering only the cron cannot silently re-enable a pipeline
607
+ * somebody turned off. The answer is the stored workflow plus `warning`,
608
+ * which is the server naming a schedule that will never fire — a draft, a
609
+ * disabled graph, an unparseable cron. A screen that dropped it would repeat
610
+ * the incident this route was written after: a scheduler announcing it was
611
+ * watching schedules while parsing nothing.
612
+ */
613
+ scheduleWorkflow(id: string, input: WorkflowScheduleInput): Promise<ScheduledWorkflow>;
614
+ /**
615
+ * What the system behind one source node looks like right now. Writes nothing.
616
+ *
617
+ * Takes a node and not a connector, and the swap is the whole of the move:
618
+ * this was `POST connectors/:id/discover`, which refused outright for any
619
+ * connector carrying a `workflowId` — and every connector carries one now, so
620
+ * the old shape would have refused every connector there is.
621
+ *
622
+ * **It answers on a draft, deliberately.** A sink cannot commit into a type
623
+ * that does not exist, so requiring a published graph would require publishing
624
+ * a graph whose target type cannot be created until it is published. What it
625
+ * does need is a graph that has been SAVED: the server reads the stored node,
626
+ * not the one on screen.
627
+ *
628
+ * Typed loosely on purpose. The shape comes from
629
+ * `@dudousxd/nestjs-catalog-pipeline`, and this package must not import that
630
+ * one — it would drag a package built for a Node process, with database
631
+ * drivers behind optional imports, into a browser bundle. `PipelineCapabilities`
632
+ * above is mirrored for exactly the same reason; `narrowDiscovery` in
633
+ * `schema-discovery.tsx` is what checks the answer at the seam.
504
634
  */
505
- runWorkflow(id: string): Promise<WorkflowRun>;
635
+ discoverSourceSchema(workflowId: string, nodeId: string): Promise<unknown>;
506
636
  /**
507
637
  * Who may do what.
508
638
  *
@@ -546,6 +676,14 @@ export declare const catalogQueryKeys: {
546
676
  all: readonly ["nestjs-catalog"];
547
677
  snapshot: readonly ["nestjs-catalog", "snapshot"];
548
678
  objects: (type: string, params: ObjectQueryParams) => readonly ["nestjs-catalog", "objects", string, ObjectQueryParams];
679
+ /**
680
+ * A type's loads, keyed by type and NOT by the read's parameters.
681
+ *
682
+ * The list is a property of the type, so paging, sorting and filtering must
683
+ * not re-ask for it — keyed under `objects(type, params)` it would be fetched
684
+ * again on every keystroke of a search box.
685
+ */
686
+ objectSnapshots: (type: string) => readonly ["nestjs-catalog", "objects", string, "snapshots"];
549
687
  /**
550
688
  * Keyed on the term, so react-query caches per term and a backspace shows the
551
689
  * previous answer instantly instead of re-asking.
@@ -560,11 +698,16 @@ export declare const catalogQueryKeys: {
560
698
  search: (term: string, limit?: number) => readonly ["nestjs-catalog", "search", string, number | null];
561
699
  /**
562
700
  * The pipeline keys are nested under one prefix so a host — or a screen that
563
- * just ran a connector — can invalidate the whole of it at once. Running a
564
- * connector changes the runs, the connector's own last-run fields, and the
565
- * catalog snapshot the load wrote into, and invalidating them one by one is
566
- * how a list ends up showing a run that finished next to a connector that
567
- * still says it never has.
701
+ * just ran a pipeline — can invalidate the whole of it at once. Running one
702
+ * changes the runs, the connector's own last-run fields, and the catalog
703
+ * snapshot the load wrote into, and invalidating them one by one is how a
704
+ * screen ends up showing a run that finished next to a pipeline that still
705
+ * says it never has.
706
+ *
707
+ * `connectors` is still here and is still worth invalidating, even though
708
+ * nothing authors one any more: publishing a graph MINTS one, unpublishing
709
+ * disables it, and deleting takes it away — so the read that says which id a
710
+ * run history is keyed on goes stale on all three.
568
711
  */
569
712
  pipeline: readonly ["nestjs-catalog", "pipeline"];
570
713
  capabilities: readonly ["nestjs-catalog", "pipeline", "capabilities"];