@dudousxd/nestjs-catalog 0.10.0 → 0.12.0

package/dist/catalog.controller.js

@@ -82,10 +82,12 @@ function createCatalogController(path, guards, decorators = []) {
         registry;
         service;
         traces;
-        constructor(registry, service, traces) {
+        workspace;
+        constructor(registry, service, traces, workspace) {
             this.registry = registry;
             this.service = service;
             this.traces = traces;
+            this.workspace = workspace;
         }
         requireTraces() {
             if (!this.traces) {
@@ -283,6 +285,28 @@ function createCatalogController(path, guards, decorators = []) {
             response.setHeader('content-disposition', `attachment; filename="${filename}"`);
             return (0, catalog_query_cache_1.toCsv)(result);
         }
+        /**
+         * Every SQL this query has ever been, newest first.
+         *
+         * `catalog:read`, the same scope `GET saved-queries/:id` asks for, because
+         * it hands back the same field one version older. Gating history harder than
+         * the current text would be gating the diff rather than the data — the
+         * caller can already read what the statement says today, and the authoring
+         * scope that `POST`/`PATCH` require is about *choosing what SQL runs*, which
+         * reading an old body is not.
+         *
+         * An empty list is a real answer: a query nobody has edited since revisions
+         * shipped may have nothing recorded. A store that keeps none at all says so
+         * rather than answering `[]`, because "we do not keep these" and "nothing
+         * has changed" are different facts and a screen would draw them the same.
+         */
+        savedQueryRevisions(id) {
+            const workspace = this.workspace;
+            if (!workspace || !(0, catalog_workspace_1.supportsSavedQueryRevisions)(workspace)) {
+                throw new common_1.BadRequestException("This catalog's workspace store keeps no revisions, so a saved query's SQL can be read but not compared with what it used to be.");
+            }
+            return workspace.listSavedQueryRevisions(id);
+        }
         dashboards() {
             return this.service.listDashboards();
         }
@@ -555,6 +579,14 @@ function createCatalogController(path, guards, decorators = []) {
         __metadata("design:paramtypes", [String, Object]),
         __metadata("design:returntype", Promise)
     ], CatalogController.prototype, "exportSavedQuery", null);
+    __decorate([
+        (0, common_1.Get)('saved-queries/:id/revisions'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
+        __param(0, (0, common_1.Param)('id')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "savedQueryRevisions", null);
     __decorate([
         (0, common_1.Get)('dashboards'),
         (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
@@ -667,8 +699,10 @@ function createCatalogController(path, guards, decorators = []) {
         (0, common_1.Controller)(path),
         __param(2, (0, common_1.Optional)()),
         __param(2, (0, common_1.Inject)(catalog_workspace_1.CATALOG_TRACE_STORE)),
+        __param(3, (0, common_1.Optional)()),
+        __param(3, (0, common_1.Inject)(catalog_workspace_1.CATALOG_WORKSPACE_STORE)),
         __metadata("design:paramtypes", [catalog_registry_base_1.CatalogRegistry,
-            catalog_service_1.CatalogService, Object])
+            catalog_service_1.CatalogService, Object, Object])
     ], CatalogController);
     if (guards.length > 0) {
         (0, common_1.UseGuards)(...guards)(CatalogController);

package/dist/catalog.pipeline.d.ts

@@ -7,6 +7,7 @@
  * schedules, retries and checkpoints, and writing a second one would mean two
  * systems each believing they decide when a load runs.
  */
+import type { CatalogRevision } from './catalog.workspace';
 /**
  * Where a connector pulls from.
  *
@@ -136,6 +137,14 @@ export declare function isTransformLanguage(value: unknown): value is TransformL
  * Versioned, because a load that produced surprising numbers is investigated
  * afterwards, and "which code ran" is the first question. Bumping the version
  * on every change costs a row and answers it.
+ *
+ * The version used to be the *whole* answer, and it was half of one: it named
+ * code that no longer existed anywhere, because one row per transform is
+ * overwritten in place. Each version's code is now recorded as a
+ * {@link CatalogRevision}, read through
+ * {@link CatalogPipelineStore.listTransformRevisions}, so the number on a run
+ * and the text it names are both retrievable. `version` still counts saves that
+ * changed the code and nothing else — see `saveTransform`.
  */
 export interface CatalogTransform {
     id: string;
@@ -223,17 +232,26 @@ export interface ConnectorRun {
     error?: string;
     startedAt: string;
     finishedAt?: string;
-    /** Which transform version ran, so a surprising load can be traced to code. */
+    /**
+     * Which transform version ran, so a surprising load can be traced to code.
+     *
+     * Traced to the code itself, now, and not only to a number: the version this
+     * names is the version of a {@link CatalogRevision}, so `transforms/:id/revisions`
+     * answers with the body that produced these rows. Until that route existed
+     * this field could only establish *that* the transform had been edited since.
+     */
     transformVersion?: number;
     /** Which workflow ran, when the connector delegated to one. */
     workflowId?: string;
     /**
      * Which *version* of it ran.
      *
-     * The same question `transformVersion` answers, asked of the graph. A
-     * workflow keeps only its latest shape — exactly as a transform keeps only
-     * its latest code — so this number is what connects a run to the graph that
-     * produced it, and the only way to know a graph has changed since.
+     * The same question `transformVersion` answers, asked of the graph — and no
+     * longer answered as well, which is worth knowing before relying on it. A
+     * workflow keeps only its latest shape (see {@link CatalogWorkflow} for why it
+     * is excluded from revisions while a transform is not), so this number
+     * connects a run to the graph that produced it and is the only way to know a
+     * graph has changed since. It cannot produce the graph.
      */
     workflowVersion?: number;
     /**
@@ -435,20 +453,77 @@ export interface WorkflowGraph {
  * the code; for a workflow it means the code *and* the wiring, so both the
  * graph version and the per-node transform versions are recorded on the run.
  *
- * Like a transform, only the latest shape is kept. Storing every past graph was
- * the alternative and was rejected for consistency: transforms already answer
- * "which code ran" with a number and no history, and a model where the graph is
- * fully recoverable but the code inside it is not would give false confidence in
- * an audit. The limitation is real and worth stating plainly — an edited graph
- * cannot be reconstructed from an old run, only identified as different.
+ * **Only the latest shape is kept, and unlike a transform it is not
+ * revisioned.** That asymmetry is a decision rather than an oversight, and this
+ * is where somebody looking for the missing feature will look, so it is argued
+ * here.
+ *
+ * A transform's code and a saved query's SQL are text a person typed, and
+ * {@link CatalogRevision} archives text: two bodies, a line differ, done. A
+ * graph is a structure. Its "body" would be JSON nobody wrote, and a text diff
+ * over it is dominated by key order and canvas positions — it would report a
+ * dragged box as a change to what the load does, which is the opposite of what
+ * {@link workflowGraphHash} is careful to exclude. Diffing graphs is a graph
+ * problem and deserves a screen that draws one, not a line differ pointed at
+ * serialised nodes.
+ *
+ * The decisive reason is the counter. {@link version} is bumped on **draft**
+ * edits deliberately — see the note on it — so that a run's `workflowVersion`
+ * can never mean two different graphs. Archiving one body per version would
+ * therefore store every autosave of a canvas somebody is still dragging boxes
+ * around on, and under the per-subject cap that {@link CATALOG_REVISION_LIMIT}
+ * imposes, that noise would evict the versions that actually ran. A counter
+ * designed to be cheap to inflate and an archive designed to be bounded do not
+ * compose; making them compose means keying the archive on behaviour rather than
+ * on saves, which is what `graphHash` already is, and that is a different
+ * feature from this one.
+ *
+ * So the limitation stays, stated plainly: an edited graph cannot be
+ * reconstructed from an old run, only identified as different. A diff screen
+ * answers for the code and the SQL and not for the wiring.
  */
+/**
+ * Whether this graph is still being drawn, or is something somebody declared
+ * finished.
+ *
+ * The distinction exists because validation used to be the gate on *saving*, and
+ * that made an unfinished graph unstorable: `saveWorkflow` refused anything
+ * `validateWorkflow` had an issue with, so a canvas with one node on it could
+ * not be written down at all and closing the tab lost it. Worse, it made the
+ * canvas lie about ordinary work — clicking "+ Sink" produces a node that is
+ * unreachable from any source and names no type, both true and both useless one
+ * second after the click, because a just-added node is unwired by construction.
+ *
+ * So the gate moved rather than loosened. Validation is now the gate on
+ * publishing, and the same `validateWorkflow` still decides — a draft is not a
+ * graph that skipped the rules, it is a graph nobody has claimed is finished
+ * yet. Everything that consumes a workflow asks for `ready`: a connector may
+ * only point at one, and a promotion may only carry one. What crosses an
+ * environment should be something a person declared done.
+ */
+export declare const WORKFLOW_STATUSES: readonly ["draft", "ready"];
+export type WorkflowStatus = (typeof WORKFLOW_STATUSES)[number];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+export declare function isWorkflowStatus(value: unknown): value is WorkflowStatus;
 export interface CatalogWorkflow {
     id: string;
     name: string;
     description?: string;
     nodes: WorkflowNode[];
     edges: WorkflowEdge[];
-    /** Bumped whenever the graph's behaviour changes. Never on a rename or a move. */
+    /** See {@link WORKFLOW_STATUSES}. A graph is `draft` until somebody publishes it. */
+    status: WorkflowStatus;
+    /**
+     * Bumped whenever the graph's behaviour changes. Never on a rename or a move.
+     *
+     * Bumped on a **draft** edit too, which looks like exactly the inflation this
+     * rule exists to prevent and is not. The counter's job is to make
+     * {@link ConnectorRun.workflowVersion} answer "which shape ran": freezing it
+     * while a graph is drafted would let a run recorded at v4 and a later run also
+     * at v4 mean two different graphs, which is the one thing that field must
+     * never do. Drafting therefore inflates a number nobody reads — cheap — rather
+     * than making a number somebody does read ambiguous.
+     */
     version: number;
     /** Fingerprint of the graph at this version. See {@link workflowGraphHash}. */
     graphHash: string;
@@ -660,7 +735,24 @@ export interface CatalogWorkflowStore {
     listWorkflows(): Promise<CatalogWorkflow[]>;
     getWorkflow(id: string): Promise<CatalogWorkflow | undefined>;
     /**
-     * Validates before it writes, and refuses naming the node.
+     * Writes. Validates only what it must.
+     *
+     * A **draft** is written without validating, which is the whole of the change
+     * and the reason {@link WORKFLOW_STATUSES} exists: a graph you have not
+     * finished has to be storable, or closing the tab loses it. A **ready**
+     * workflow is still validated on every save, because it is the one that runs.
+     *
+     * `status` is not an input. A save cannot promote a draft to ready — that is
+     * {@link publishWorkflow}, which exists so there is one place that validates
+     * and one place that can explain why it refused. A save of an already-ready
+     * workflow keeps it ready, and **refuses an edit that would make it invalid**
+     * rather than quietly demoting it to draft. Demotion was the other option and
+     * it is the one that loses a running pipeline silently: a connector may only
+     * point at a ready graph, so a save that dropped the status would disable a
+     * scheduled load with nothing said to anybody. Refusing puts the error in
+     * front of the person who is editing, at the moment they edit. To park a
+     * broken idea on a live graph, {@link unpublishWorkflow} it first and be told
+     * which connectors that stops.
      *
      * `version`, `graphHash` and `targetType` are not inputs: the first two are
      * derived from the graph and the third from the sink, and accepting them from
@@ -670,6 +762,34 @@ export interface CatalogWorkflowStore {
         id?: string;
         description?: string;
     }, createdBy: string): Promise<CatalogWorkflow>;
+    /**
+     * Declare a graph finished: validate it, and make it `ready`.
+     *
+     * A transition rather than a field on save, and the argument is that this is
+     * the only shape with somewhere to put the refusal. "Ready" is a claim that
+     * has to be checked, and a check that fails owes an explanation naming the
+     * nodes — `validateWorkflow` produces exactly that, and a boolean field on a
+     * save request has nowhere to return it that is not an error on an operation
+     * the caller thought was about something else. It also makes the audit
+     * question answerable: publishing is an act with an actor, and a field set in
+     * passing during an autosave is not.
+     *
+     * Idempotent on an already-ready graph, because the honest answer to "publish
+     * this thing that is published" is the graph, not an error.
+     */
+    publishWorkflow(id: string, publishedBy: string): Promise<CatalogWorkflow>;
+    /**
+     * Take a graph back to `draft`.
+     *
+     * **Refuses while any connector still runs it**, exactly as
+     * {@link deleteWorkflow} does and for the same reason: a connector may only
+     * point at a ready graph, so unpublishing one out from under a schedule breaks
+     * a load that was working, and the operator needs to know *which* connectors
+     * to point elsewhere first. Refusing here rather than cascading is deliberate —
+     * disabling somebody's connectors as a side effect of an edit to something
+     * else is precisely the silent action this status exists to prevent.
+     */
+    unpublishWorkflow(id: string, unpublishedBy: string): Promise<CatalogWorkflow>;
     /** Refuses while any connector still runs it. */
     deleteWorkflow(id: string): Promise<boolean>;
     /** Which connectors run it. Named, so a refusal can say. */
@@ -724,6 +844,13 @@ export interface CatalogStageStore {
  * does, because a flag is a claim and a method is the thing itself.
  */
 export declare function supportsWorkflows(store: CatalogPipelineStore): store is CatalogPipelineStore & CatalogWorkflowStore;
+/**
+ * Whether this store keeps a transform's history.
+ *
+ * The method rather than a flag, exactly as {@link supportsWorkflows} argues: a
+ * flag is a claim and a method is the thing itself.
+ */
+export declare function supportsTransformRevisions(store: CatalogPipelineStore): store is CatalogPipelineStore & Required<Pick<CatalogPipelineStore, 'listTransformRevisions'>>;
 export declare function supportsWorkflowStages(store: CatalogPipelineStore): store is CatalogPipelineStore & CatalogStageStore;
 export interface CatalogPipelineStore extends Partial<CatalogWorkflowStore>, Partial<CatalogStageStore> {
     listConnectors(): Promise<CatalogConnector[]>;
@@ -762,6 +889,22 @@ export interface CatalogPipelineStore extends Partial<CatalogWorkflowStore>, Par
         description?: string;
     }, createdBy: string): Promise<CatalogTransform>;
     deleteTransform(id: string): Promise<boolean>;
+    /**
+     * Every version of this transform's code, newest first.
+     *
+     * **Optional**, mixed in for the same reason {@link CatalogWorkflowStore} is:
+     * a store written against the previous shape of this interface still
+     * implements it, and turning that into a compile error would be a breaking
+     * change for an additive feature. {@link supportsTransformRevisions} is how a
+     * caller asks, so a deployment whose store keeps no history gets a sentence
+     * rather than a method that is missing at run time.
+     *
+     * The list is what makes `transformVersion` on a run mean something: the
+     * revision whose {@link CatalogRevision.version} equals it holds the code that
+     * produced those rows. Bounded — see {@link CATALOG_REVISION_LIMIT} for what
+     * that bound costs.
+     */
+    listTransformRevisions?(id: string): Promise<CatalogRevision[]>;
     startRun(input: {
         connectorId: string;
         snapshotId: string;

package/dist/catalog.pipeline.js

@@ -9,10 +9,11 @@
  * systems each believing they decide when a load runs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.TRANSFORM_RUNNER = exports.TRANSFORM_LANGUAGES = exports.CONNECTOR_KINDS = void 0;
+exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.TRANSFORM_RUNNER = exports.TRANSFORM_LANGUAGES = exports.CONNECTOR_KINDS = void 0;
 exports.isConnectorKind = isConnectorKind;
 exports.isTransformLanguage = isTransformLanguage;
 exports.isWorkflowNodeKind = isWorkflowNodeKind;
+exports.isWorkflowStatus = isWorkflowStatus;
 exports.isWorkflowExecutionMode = isWorkflowExecutionMode;
 exports.validateWorkflow = validateWorkflow;
 exports.workflowRunOrder = workflowRunOrder;
@@ -20,6 +21,7 @@ exports.workflowGraphHash = workflowGraphHash;
 exports.isWorkflowNode = isWorkflowNode;
 exports.isWorkflowEdge = isWorkflowEdge;
 exports.supportsWorkflows = supportsWorkflows;
+exports.supportsTransformRevisions = supportsTransformRevisions;
 exports.supportsWorkflowStages = supportsWorkflowStages;
 exports.isPipelineStore = isPipelineStore;
 /**
@@ -136,6 +138,79 @@ function isWorkflowNodeKind(value) {
  * separator would let one node read another's rows.
  */
 exports.WORKFLOW_NODE_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * An authored graph of steps ending in one commit.
+ *
+ * Versioned the way {@link CatalogTransform} is, and for the same question: a
+ * load that produced surprising numbers is investigated afterwards, and "what
+ * ran" is the first thing asked. For a single-transform connector that means
+ * the code; for a workflow it means the code *and* the wiring, so both the
+ * graph version and the per-node transform versions are recorded on the run.
+ *
+ * **Only the latest shape is kept, and unlike a transform it is not
+ * revisioned.** That asymmetry is a decision rather than an oversight, and this
+ * is where somebody looking for the missing feature will look, so it is argued
+ * here.
+ *
+ * A transform's code and a saved query's SQL are text a person typed, and
+ * {@link CatalogRevision} archives text: two bodies, a line differ, done. A
+ * graph is a structure. Its "body" would be JSON nobody wrote, and a text diff
+ * over it is dominated by key order and canvas positions — it would report a
+ * dragged box as a change to what the load does, which is the opposite of what
+ * {@link workflowGraphHash} is careful to exclude. Diffing graphs is a graph
+ * problem and deserves a screen that draws one, not a line differ pointed at
+ * serialised nodes.
+ *
+ * The decisive reason is the counter. {@link version} is bumped on **draft**
+ * edits deliberately — see the note on it — so that a run's `workflowVersion`
+ * can never mean two different graphs. Archiving one body per version would
+ * therefore store every autosave of a canvas somebody is still dragging boxes
+ * around on, and under the per-subject cap that {@link CATALOG_REVISION_LIMIT}
+ * imposes, that noise would evict the versions that actually ran. A counter
+ * designed to be cheap to inflate and an archive designed to be bounded do not
+ * compose; making them compose means keying the archive on behaviour rather than
+ * on saves, which is what `graphHash` already is, and that is a different
+ * feature from this one.
+ *
+ * So the limitation stays, stated plainly: an edited graph cannot be
+ * reconstructed from an old run, only identified as different. A diff screen
+ * answers for the code and the SQL and not for the wiring.
+ */
+/**
+ * Whether this graph is still being drawn, or is something somebody declared
+ * finished.
+ *
+ * The distinction exists because validation used to be the gate on *saving*, and
+ * that made an unfinished graph unstorable: `saveWorkflow` refused anything
+ * `validateWorkflow` had an issue with, so a canvas with one node on it could
+ * not be written down at all and closing the tab lost it. Worse, it made the
+ * canvas lie about ordinary work — clicking "+ Sink" produces a node that is
+ * unreachable from any source and names no type, both true and both useless one
+ * second after the click, because a just-added node is unwired by construction.
+ *
+ * So the gate moved rather than loosened. Validation is now the gate on
+ * publishing, and the same `validateWorkflow` still decides — a draft is not a
+ * graph that skipped the rules, it is a graph nobody has claimed is finished
+ * yet. Everything that consumes a workflow asks for `ready`: a connector may
+ * only point at one, and a promotion may only carry one. What crosses an
+ * environment should be something a person declared done.
+ */
+exports.WORKFLOW_STATUSES = [
+    /**
+     * Being drawn. Saves without validating, and cannot run, be scheduled, or be
+     * promoted. An incomplete node here is the normal state rather than an alarm.
+     */
+    'draft',
+    /**
+     * Declared finished, and validated at the moment it was declared. This is the
+     * only status a connector may point at and the only one a promotion carries.
+     */
+    'ready',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowStatus(value) {
+    return exports.WORKFLOW_STATUSES.some((status) => status === value);
+}
 /**
  * How a workflow run is executed here.
  *
@@ -634,7 +709,22 @@ function isWorkflowEdge(value) {
 function supportsWorkflows(store) {
     return (typeof store.listWorkflows === 'function' &&
         typeof store.getWorkflow === 'function' &&
-        typeof store.saveWorkflow === 'function');
+        typeof store.saveWorkflow === 'function' &&
+        // Asked for by name like the rest, rather than assumed to come with
+        // `saveWorkflow`. Promotion publishes what it saves, so a store that has the
+        // save and not the transition would narrow cleanly here and then fail one
+        // call later, in the middle of an apply that has already written types and
+        // transforms into the target.
+        typeof store.publishWorkflow === 'function');
+}
+/**
+ * Whether this store keeps a transform's history.
+ *
+ * The method rather than a flag, exactly as {@link supportsWorkflows} argues: a
+ * flag is a claim and a method is the thing itself.
+ */
+function supportsTransformRevisions(store) {
+    return typeof store.listTransformRevisions === 'function';
 }
 function supportsWorkflowStages(store) {
     return typeof store.writeStage === 'function' && typeof store.readStage === 'function';