@dudousxd/nestjs-catalog 0.11.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,12 +453,34 @@ 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
@@ -804,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[]>;
@@ -842,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

@@ -21,6 +21,7 @@ exports.workflowGraphHash = workflowGraphHash;
 exports.isWorkflowNode = isWorkflowNode;
 exports.isWorkflowEdge = isWorkflowEdge;
 exports.supportsWorkflows = supportsWorkflows;
+exports.supportsTransformRevisions = supportsTransformRevisions;
 exports.supportsWorkflowStages = supportsWorkflowStages;
 exports.isPipelineStore = isPipelineStore;
 /**
@@ -146,12 +147,34 @@ exports.WORKFLOW_NODE_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
  * 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
@@ -694,6 +717,15 @@ function supportsWorkflows(store) {
         // 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';
 }

package/dist/catalog.workspace.d.ts

@@ -11,6 +11,16 @@ export interface SavedQuery {
     id: string;
     name: string;
     description?: string;
+    /**
+     * The statement, as it is now.
+     *
+     * Overwritten in place by {@link CatalogWorkspaceStore.updateSavedQuery}, and
+     * for a long time that was the end of it — a report that started answering
+     * differently left nothing to compare against, not even a version number. What
+     * it used to say is kept as {@link CatalogRevision}s now, read through
+     * {@link CatalogWorkspaceStore.listSavedQueryRevisions}; this field stays the
+     * one a run of the query executes.
+     */
     sql: string;
     /** Free-form grouping, the way a folder would work without being one. */
     folder?: string;
@@ -71,6 +81,122 @@ export interface SaveQueryInput {
     visualization?: QueryVisualization;
     shared?: boolean;
 }
+/**
+ * One recorded revision of something whose text a person edits.
+ *
+ * The same shape for a transform's code and for a saved query's SQL, and that is
+ * the point rather than a saving: the two are edited the same way and go wrong
+ * the same way — somebody changes the text, a load or a report starts coming out
+ * different, and the question afterwards is what the text used to say. `body` is
+ * named for that. `code` would have been a lie on half of its uses.
+ *
+ * ## What this exists to fix
+ *
+ * A {@link ConnectorRun} has always recorded `transformVersion`, so the catalog
+ * already knew *which* version produced a given load. What it did not keep was
+ * the text of that version: one row per transform, overwritten in place, the
+ * counter bumped and the previous code gone. A saved query had not even the
+ * counter. Meanwhile the runs list renders `code v3`, which reads as a reference
+ * to something retrievable — so an operator was told a version number, believed
+ * the source was recoverable, and it was not.
+ *
+ * The number on the run and the {@link version} here are **the same number**.
+ * That is the whole contract: "this load ran v3" becomes something a person can
+ * open.
+ *
+ * ## No `kind` field, deliberately
+ *
+ * A revision is always read through a route that already names its subject —
+ * `transforms/:id/revisions`, `saved-queries/:id/revisions` — so a discriminator
+ * here would be a field whose only possible value the caller had just supplied.
+ * The *store* keys by one, because one table holds both kinds; that is a storage
+ * concern and it stays in the store.
+ *
+ * ## What is NOT revisioned, and why
+ *
+ * A workflow graph, which has the identical "latest only" limitation and is
+ * deliberately left with it. See {@link CatalogWorkflow}, which makes the
+ * argument where somebody looking for the missing feature will find it.
+ */
+export interface CatalogRevision {
+    /**
+     * Stable id of this revision.
+     *
+     * Derived from the subject and the version rather than random — see
+     * `revisionKey` in the MikroORM store — so recording the same version twice
+     * replaces it instead of appending a second copy, and a screen may key a list
+     * on it across refetches.
+     */
+    id: string;
+    /** What it belongs to — a transform id or a saved-query id. */
+    subjectId: string;
+    /** The version this revision IS. Matches `transformVersion` on a run. */
+    version: number;
+    /** The text as it was: the transform's code, or the query's SQL. */
+    body: string;
+    /**
+     * Who saved it.
+     *
+     * Exact for a transform, which is saved through a store method that is given
+     * the actor. **Approximate for a saved query**, whose update path is given
+     * none — `updateSavedQuery` takes an id and a patch, and `CatalogService`
+     * keeps the actor for the audit event it emits — so a saved query's revisions
+     * are attributed to the query's `createdBy`. That is who created it, not
+     * necessarily who last edited it, and it is recorded that way rather than
+     * invented: a name here that was picked to fill the field would be read as
+     * evidence. Threading the editor through `updateSavedQuery` is what would fix
+     * it, and it is a change to that method's contract rather than to this one.
+     */
+    authoredBy: string;
+    authoredAt: string;
+}
+/**
+ * How many revisions are kept per subject. Writing a newer one drops the oldest
+ * beyond this.
+ *
+ * ## Why there is a cap at all
+ *
+ * This is append-only text that grows forever, and it is the fourth append-only
+ * table in the bundled store. The other three earn their unboundedness and this
+ * one does not. An audit event and a connector run are each one small row per
+ * *thing that happened*, at a rate an operator can read off their own load
+ * schedule; staged rows are dropped the moment the run that produced them is
+ * finished with. A revision is neither: it grows with how often somebody edits,
+ * which nobody meters, and every row carries a whole code body rather than a
+ * counter. Unpredictable in rate *and* large per row is the combination worth
+ * bounding — and "this grows; here is the query to prune it" would have been a
+ * fourth unbounded table with a paragraph in front of it.
+ *
+ * ## Why a count per subject rather than an age bound
+ *
+ * An age bound keys the wrong thing. A transform edited twice in 2019 and relied
+ * on ever since would lose both revisions, while one edited daily keeps
+ * everything — exactly backwards. What makes a revision unrecoverable is being
+ * superseded, so that is what the bound counts.
+ *
+ * ## What it costs, stated rather than implied
+ *
+ * A run's `transformVersion` can name a revision that has been evicted: a
+ * transform saved more than this many times can no longer produce its earliest
+ * code. That loss is real. It is strictly smaller than the one it replaces —
+ * where every version but the newest was unrecoverable — and it is visible
+ * rather than silent, because a caller holding a version older than the oldest
+ * revision in the list can see that the list does not reach that far.
+ *
+ * At the cap a 4 KB body costs 200 KB per subject, so a thousand heavily-edited
+ * subjects cost roughly 200 MB. That is a ceiling, which is the point of having
+ * one.
+ *
+ * ## Why a constant and not a module option
+ *
+ * The number is part of what this table promises, and a console should be able
+ * to print "the last 50 are kept" without a round trip to ask which deployment
+ * it is talking to. A knob is also a promise to support every value of it,
+ * including the one that switches the feature off and is then reported as a bug.
+ * It becomes an option on the day there is a deployment it is wrong for, rather
+ * than in anticipation of one.
+ */
+export declare const CATALOG_REVISION_LIMIT = 50;
 export interface Dashboard {
     id: string;
     name: string;
@@ -480,6 +606,26 @@ export interface CatalogWorkspaceStore {
      * first and decides.
      */
     deleteSavedQuery(id: string): Promise<boolean>;
+    /**
+     * Every SQL this saved query has ever been, newest first.
+     *
+     * **Optional**, and mixed in here rather than made a member every store must
+     * have, for the reason {@link CatalogWorkflowStore} gives about the same
+     * decision: a store written against the previous shape of this interface —
+     * including the routing proxy in the MikroORM package — implements
+     * `CatalogWorkspaceStore` today, and turning that into a compile error would
+     * be a breaking change for a feature that is purely additive.
+     * {@link supportsSavedQueryRevisions} is how a caller asks, so "this store
+     * keeps no revisions" is a sentence a route can say rather than a method that
+     * is missing at run time.
+     *
+     * An EMPTY list is a real answer and never an error: a query nobody has edited
+     * since this shipped may genuinely have nothing recorded. What the bundled
+     * store does about that — see `readRevisions` — is a store's decision, and a
+     * consumer must read "nothing recorded" as itself rather than as "nothing has
+     * changed".
+     */
+    listSavedQueryRevisions?(id: string): Promise<CatalogRevision[]>;
     listDashboards(): Promise<Dashboard[]>;
     getDashboard(id: string): Promise<Dashboard | undefined>;
     saveDashboard(input: {
@@ -498,5 +644,13 @@ export interface CatalogWorkspaceStore {
     recordEvent(event: Omit<CatalogAuditEvent, 'id'>): Promise<void>;
     listEvents(query: AuditQuery): Promise<CatalogAuditEvent[]>;
 }
+/**
+ * Whether this store keeps a saved query's history.
+ *
+ * Checks the method rather than a flag, the same way {@link isWorkspaceStore}
+ * and `supportsWorkflows` do: a flag is a claim and a method is the thing
+ * itself.
+ */
+export declare function supportsSavedQueryRevisions(store: CatalogWorkspaceStore): store is CatalogWorkspaceStore & Required<Pick<CatalogWorkspaceStore, 'listSavedQueryRevisions'>>;
 export declare function isWorkspaceStore(store: unknown): store is CatalogWorkspaceStore;
 export declare const CATALOG_WORKSPACE_STORE: unique symbol;

package/dist/catalog.workspace.js

@@ -9,12 +9,60 @@
  * mount the catalog without any of this and notice nothing missing.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = void 0;
+exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = exports.CATALOG_REVISION_LIMIT = void 0;
 exports.isCatalogTraceOutcome = isCatalogTraceOutcome;
 exports.traceOutcomeFilter = traceOutcomeFilter;
 exports.isTraceStore = isTraceStore;
 exports.embeddedVisualization = embeddedVisualization;
+exports.supportsSavedQueryRevisions = supportsSavedQueryRevisions;
 exports.isWorkspaceStore = isWorkspaceStore;
+/**
+ * How many revisions are kept per subject. Writing a newer one drops the oldest
+ * beyond this.
+ *
+ * ## Why there is a cap at all
+ *
+ * This is append-only text that grows forever, and it is the fourth append-only
+ * table in the bundled store. The other three earn their unboundedness and this
+ * one does not. An audit event and a connector run are each one small row per
+ * *thing that happened*, at a rate an operator can read off their own load
+ * schedule; staged rows are dropped the moment the run that produced them is
+ * finished with. A revision is neither: it grows with how often somebody edits,
+ * which nobody meters, and every row carries a whole code body rather than a
+ * counter. Unpredictable in rate *and* large per row is the combination worth
+ * bounding — and "this grows; here is the query to prune it" would have been a
+ * fourth unbounded table with a paragraph in front of it.
+ *
+ * ## Why a count per subject rather than an age bound
+ *
+ * An age bound keys the wrong thing. A transform edited twice in 2019 and relied
+ * on ever since would lose both revisions, while one edited daily keeps
+ * everything — exactly backwards. What makes a revision unrecoverable is being
+ * superseded, so that is what the bound counts.
+ *
+ * ## What it costs, stated rather than implied
+ *
+ * A run's `transformVersion` can name a revision that has been evicted: a
+ * transform saved more than this many times can no longer produce its earliest
+ * code. That loss is real. It is strictly smaller than the one it replaces —
+ * where every version but the newest was unrecoverable — and it is visible
+ * rather than silent, because a caller holding a version older than the oldest
+ * revision in the list can see that the list does not reach that far.
+ *
+ * At the cap a 4 KB body costs 200 KB per subject, so a thousand heavily-edited
+ * subjects cost roughly 200 MB. That is a ceiling, which is the point of having
+ * one.
+ *
+ * ## Why a constant and not a module option
+ *
+ * The number is part of what this table promises, and a console should be able
+ * to print "the last 50 are kept" without a round trip to ask which deployment
+ * it is talking to. A knob is also a promise to support every value of it,
+ * including the one that switches the feature off and is then reported as a bug.
+ * It becomes an option on the day there is a deployment it is wrong for, rather
+ * than in anticipation of one.
+ */
+exports.CATALOG_REVISION_LIMIT = 50;
 /**
  * The same events, told as stories instead of as a list.
  *
@@ -102,6 +150,16 @@ function embeddedVisualization(saved, cardLibrary) {
     const base = saved ?? { kind: 'table' };
     return cardLibrary ? { ...base, library: cardLibrary } : base;
 }
+/**
+ * Whether this store keeps a saved query's history.
+ *
+ * Checks the method rather than a flag, the same way {@link isWorkspaceStore}
+ * and `supportsWorkflows` do: a flag is a claim and a method is the thing
+ * itself.
+ */
+function supportsSavedQueryRevisions(store) {
+    return typeof store.listSavedQueryRevisions === 'function';
+}
 function isWorkspaceStore(store) {
     return (typeof store === 'object' &&
         store !== null &&

package/dist/client.d.ts

@@ -9,7 +9,8 @@
  * own UI. The endpoints alone are not an API; the endpoints plus the response
  * types are.
  */
-export type { AuditQuery, CatalogAuditEvent, Dashboard, DashboardCard, QueryVisualization, SaveQueryInput, SavedQuery, } from './catalog.workspace';
+export type { AuditQuery, CatalogAuditEvent, CatalogRevision, Dashboard, DashboardCard, QueryVisualization, SaveQueryInput, SavedQuery, } from './catalog.workspace';
+export { CATALOG_REVISION_LIMIT } from './catalog.workspace';
 export type { CatalogQueryRelation, CatalogQueryRequest, CatalogQueryResult, } from './catalog.query';
 export type { CatalogSearchField, CatalogSearchHit, CatalogSearchKind, CatalogSearchRank, CatalogSearchResult, } from './search.types';
 export type { CatalogGraph, CatalogObjectPage, CatalogObjectQuery, CatalogObjectTypeDef, CatalogOverlay, CatalogPropertyDef, CatalogRelationDef, CatalogSnapshot, RelationKind, ScalarType, } from './catalog.types';
@@ -66,6 +67,15 @@ export declare const catalogRoutes: {
     readonly workspaceCapabilities: () => string;
     readonly savedQueries: () => string;
     readonly savedQuery: (id: string) => string;
+    /**
+     * Every SQL this query has ever been.
+     *
+     * A sub-resource of the saved query rather than a `?version=` on it, because
+     * the question a diff screen asks first is "what were all of them" — it has to
+     * see the list before it knows which two to compare, and one request that
+     * answers that beats a list plus two fetches.
+     */
+    readonly savedQueryRevisions: (id: string) => string;
     readonly runSavedQuery: (id: string) => string;
     readonly exportSavedQuery: (id: string) => string;
     readonly dashboards: () => string;

package/dist/client.js

@@ -11,7 +11,12 @@
  * types are.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowExecutionMode = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.isWorkflowNode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.catalogRoutes = void 0;
+exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowExecutionMode = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.isWorkflowNode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.catalogRoutes = exports.CATALOG_REVISION_LIMIT = void 0;
+// A value, not a type: a screen saying how far back the history goes should read
+// the number rather than print one of its own. See its docblock for what the cap
+// costs.
+var catalog_workspace_1 = require("./catalog.workspace");
+Object.defineProperty(exports, "CATALOG_REVISION_LIMIT", { enumerable: true, get: function () { return catalog_workspace_1.CATALOG_REVISION_LIMIT; } });
 /**
  * Builds the paths the catalog controller serves, relative to wherever it was
  * mounted. Kept as string builders rather than a fetch wrapper so the host
@@ -40,6 +45,15 @@ exports.catalogRoutes = {
     workspaceCapabilities: () => '/catalog/workspace/capabilities',
     savedQueries: () => '/catalog/saved-queries',
     savedQuery: (id) => `/catalog/saved-queries/${encodeURIComponent(id)}`,
+    /**
+     * Every SQL this query has ever been.
+     *
+     * A sub-resource of the saved query rather than a `?version=` on it, because
+     * the question a diff screen asks first is "what were all of them" — it has to
+     * see the list before it knows which two to compare, and one request that
+     * answers that beats a list plus two fetches.
+     */
+    savedQueryRevisions: (id) => `/catalog/saved-queries/${encodeURIComponent(id)}/revisions`,
     runSavedQuery: (id) => `/catalog/saved-queries/${encodeURIComponent(id)}/run`,
     exportSavedQuery: (id) => `/catalog/saved-queries/${encodeURIComponent(id)}/export.csv`,
     dashboards: () => '/catalog/dashboards',

package/dist/index.d.ts

@@ -8,14 +8,14 @@ export { type CatalogOverlayStore, FileCatalogOverlayStore, InMemoryCatalogOverl
 export { CATALOG_OVERLAY_STORE } from './catalog.overlay-store.token';
 export { MikroOrmCatalogRegistry } from './catalog.registry';
 export { CatalogRegistry } from './catalog.registry.base';
-export { CATALOG_PIPELINE_STORE, type CatalogConnection, type CatalogConnector, type ConnectionCheck, CONNECTOR_KINDS, type CatalogPipelineStore, type CatalogStageStore, type CatalogTransform, type CatalogWorkflow, type CatalogWorkflowCapabilities, type CatalogWorkflowStore, type ConnectorKind, type ConnectorRun, isConnectorKind, isPipelineStore, isTransformLanguage, isWorkflowEdge, isWorkflowExecutionMode, isWorkflowNode, isWorkflowNodeKind, isWorkflowStatus, supportsWorkflows, supportsWorkflowStages, TRANSFORM_RUNNER, TRANSFORM_LANGUAGES, type TransformLanguage, type TransformResult, type TransformRunner, validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_STATUSES, type WorkflowEdge, type WorkflowExecutionMode, type WorkflowGraph, workflowGraphHash, type WorkflowIssueCode, type WorkflowNode, type WorkflowNodeKind, type WorkflowNodeOutcome, type WorkflowNodeStepInput, type WorkflowNodeStepOutput, workflowRunOrder, type WorkflowSinkNode, type WorkflowSourceNode, type WorkflowStageRef, type WorkflowStatus, type WorkflowTransformNode, type WorkflowValidationIssue, } from './catalog.pipeline';
+export { CATALOG_PIPELINE_STORE, type CatalogConnection, type CatalogConnector, type ConnectionCheck, CONNECTOR_KINDS, type CatalogPipelineStore, type CatalogStageStore, type CatalogTransform, type CatalogWorkflow, type CatalogWorkflowCapabilities, type CatalogWorkflowStore, type ConnectorKind, type ConnectorRun, isConnectorKind, isPipelineStore, isTransformLanguage, supportsTransformRevisions, isWorkflowEdge, isWorkflowExecutionMode, isWorkflowNode, isWorkflowNodeKind, isWorkflowStatus, supportsWorkflows, supportsWorkflowStages, TRANSFORM_RUNNER, TRANSFORM_LANGUAGES, type TransformLanguage, type TransformResult, type TransformRunner, validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_STATUSES, type WorkflowEdge, type WorkflowExecutionMode, type WorkflowGraph, workflowGraphHash, type WorkflowIssueCode, type WorkflowNode, type WorkflowNodeKind, type WorkflowNodeOutcome, type WorkflowNodeStepInput, type WorkflowNodeStepOutput, workflowRunOrder, type WorkflowSinkNode, type WorkflowSourceNode, type WorkflowStageRef, type WorkflowStatus, type WorkflowTransformNode, type WorkflowValidationIssue, } from './catalog.pipeline';
 export * from './catalog.environment';
 export { QueryCache, toCsv } from './catalog.query-cache';
 export { SubprocessTransformRunner, type TransformRunnerOptions, } from './transform-runner';
 export { CatalogService } from './catalog.service';
 export { DEFAULT_SEARCH_LIMIT, MAX_SEARCH_LIMIT, bestMatch, emptySearch, maySearch, type SearchInput, type SearchableDashboard, type SearchableSavedQuery, searchCatalog, visibleToPrincipal, } from './search';
 export type { CatalogSearchField, CatalogSearchHit, CatalogSearchKind, CatalogSearchRank, CatalogSearchResult, } from './search.types';
-export { type AuditQuery, CATALOG_TRACE_OUTCOMES, CATALOG_TRACE_STORE, CATALOG_WORKSPACE_STORE, type CatalogAuditEvent, type CatalogTrace, type CatalogTraceList, type CatalogTraceOutcome, type CatalogTraceSpan, type CatalogTraceStore, type CatalogTraceTotals, type CatalogUnlinkedList, type CatalogWorkspaceStore, type Dashboard, type DashboardCard, type EmbeddedChart, type EmbeddedChartPlacement, type EmbeddedDashboard, embeddedVisualization, isCatalogTraceOutcome, isTraceStore, isWorkspaceStore, type QueryVisualization, type SaveQueryInput, type SavedQuery, type TraceQuery, traceOutcomeFilter, } from './catalog.workspace';
+export { type AuditQuery, CATALOG_REVISION_LIMIT, CATALOG_TRACE_OUTCOMES, CATALOG_TRACE_STORE, CATALOG_WORKSPACE_STORE, type CatalogAuditEvent, type CatalogRevision, type CatalogTrace, type CatalogTraceList, type CatalogTraceOutcome, type CatalogTraceSpan, type CatalogTraceStore, type CatalogTraceTotals, type CatalogUnlinkedList, type CatalogWorkspaceStore, type Dashboard, type DashboardCard, type EmbeddedChart, type EmbeddedChartPlacement, type EmbeddedDashboard, embeddedVisualization, isCatalogTraceOutcome, isTraceStore, isWorkspaceStore, type QueryVisualization, type SaveQueryInput, type SavedQuery, supportsSavedQueryRevisions, type TraceQuery, traceOutcomeFilter, } from './catalog.workspace';
 export { CATALOG_PRINCIPAL_RESOLVER, type CatalogActor, type CatalogGrants, type CatalogPrincipal, type CatalogPrincipalResolver, type CatalogScope, composePrincipalId, delegatePrincipal, expandScopes, hasScope, parsePrincipalId, PRINCIPAL_ACTOR_SEPARATOR, maySeeClassification, mayRead, mayWrite, readableObjectPage, StaticKeyPrincipalResolver, } from './catalog.principal';
 export * from './catalog.access';
 export { assertNoColumnCollisions, CATALOG_RESERVED_COLUMNS, CATALOG_SNAPSHOT_MODES, CATALOG_STORE, type CarryForwardResult, type CatalogColumnCollision, CatalogColumnCollisionError, type CatalogMergeStore, type CatalogReadQuery, type CatalogReadResult, type CatalogReadStore, type CatalogReservedColumn, type CatalogSnapshotMode, type CatalogStoreCapabilities, type CatalogWriteStore, type ColumnCollisionOptions, findColumnCollisions, isCatalogStoreCapabilities, isReservedColumn, isWriteStore, type SnapshotRef, supportsCarryForward, } from './catalog.store';

package/dist/index.js

@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.emptySearch = exports.bestMatch = exports.MAX_SEARCH_LIMIT = exports.DEFAULT_SEARCH_LIMIT = exports.CatalogService = exports.SubprocessTransformRunner = exports.toCsv = exports.QueryCache = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.TRANSFORM_RUNNER = exports.supportsWorkflowStages = exports.supportsWorkflows = exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowNode = exports.isWorkflowExecutionMode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isPipelineStore = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.CATALOG_PIPELINE_STORE = exports.CatalogRegistry = exports.MikroOrmCatalogRegistry = exports.CATALOG_OVERLAY_STORE = exports.InMemoryCatalogOverlayStore = exports.FileCatalogOverlayStore = exports.CATALOG_OPTIONS = exports.isQueryStore = exports.assertReadOnlyShape = exports.CatalogModule = exports.emitCatalog = exports.curationActor = exports.channelNameFor = exports.catalogEventPhase = exports.UNATTRIBUTED_PRINCIPAL_ID = exports.CATALOG_LIB = exports.CATALOG_EVENTS = exports.CATALOG_EVENT_PHASE_FALLBACK = exports.CATALOG_EVENT_PHASE = exports.CatalogType = exports.CatalogProperty = void 0;
-exports.RequireScopes = exports.RequireHuman = exports.REQUIRES_HUMAN = exports.REQUIRED_SCOPES = exports.MikroOrmReadStore = exports.supportsCarryForward = exports.isWriteStore = exports.isReservedColumn = exports.isCatalogStoreCapabilities = exports.findColumnCollisions = exports.CatalogColumnCollisionError = exports.CATALOG_STORE = exports.CATALOG_SNAPSHOT_MODES = exports.CATALOG_RESERVED_COLUMNS = exports.assertNoColumnCollisions = exports.StaticKeyPrincipalResolver = exports.readableObjectPage = exports.mayWrite = exports.mayRead = exports.maySeeClassification = exports.PRINCIPAL_ACTOR_SEPARATOR = exports.parsePrincipalId = exports.hasScope = exports.expandScopes = exports.delegatePrincipal = exports.composePrincipalId = exports.CATALOG_PRINCIPAL_RESOLVER = exports.traceOutcomeFilter = exports.isWorkspaceStore = exports.isTraceStore = exports.isCatalogTraceOutcome = exports.embeddedVisualization = exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = exports.visibleToPrincipal = exports.searchCatalog = exports.maySearch = void 0;
+exports.bestMatch = exports.MAX_SEARCH_LIMIT = exports.DEFAULT_SEARCH_LIMIT = exports.CatalogService = exports.SubprocessTransformRunner = exports.toCsv = exports.QueryCache = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.TRANSFORM_RUNNER = exports.supportsWorkflowStages = exports.supportsWorkflows = exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowNode = exports.isWorkflowExecutionMode = exports.isWorkflowEdge = exports.supportsTransformRevisions = exports.isTransformLanguage = exports.isPipelineStore = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.CATALOG_PIPELINE_STORE = exports.CatalogRegistry = exports.MikroOrmCatalogRegistry = exports.CATALOG_OVERLAY_STORE = exports.InMemoryCatalogOverlayStore = exports.FileCatalogOverlayStore = exports.CATALOG_OPTIONS = exports.isQueryStore = exports.assertReadOnlyShape = exports.CatalogModule = exports.emitCatalog = exports.curationActor = exports.channelNameFor = exports.catalogEventPhase = exports.UNATTRIBUTED_PRINCIPAL_ID = exports.CATALOG_LIB = exports.CATALOG_EVENTS = exports.CATALOG_EVENT_PHASE_FALLBACK = exports.CATALOG_EVENT_PHASE = exports.CatalogType = exports.CatalogProperty = void 0;
+exports.RequireScopes = exports.RequireHuman = exports.REQUIRES_HUMAN = exports.REQUIRED_SCOPES = exports.MikroOrmReadStore = exports.supportsCarryForward = exports.isWriteStore = exports.isReservedColumn = exports.isCatalogStoreCapabilities = exports.findColumnCollisions = exports.CatalogColumnCollisionError = exports.CATALOG_STORE = exports.CATALOG_SNAPSHOT_MODES = exports.CATALOG_RESERVED_COLUMNS = exports.assertNoColumnCollisions = exports.StaticKeyPrincipalResolver = exports.readableObjectPage = exports.mayWrite = exports.mayRead = exports.maySeeClassification = exports.PRINCIPAL_ACTOR_SEPARATOR = exports.parsePrincipalId = exports.hasScope = exports.expandScopes = exports.delegatePrincipal = exports.composePrincipalId = exports.CATALOG_PRINCIPAL_RESOLVER = exports.traceOutcomeFilter = exports.supportsSavedQueryRevisions = exports.isWorkspaceStore = exports.isTraceStore = exports.isCatalogTraceOutcome = exports.embeddedVisualization = exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = exports.CATALOG_REVISION_LIMIT = exports.visibleToPrincipal = exports.searchCatalog = exports.maySearch = exports.emptySearch = void 0;
 var catalog_decorators_1 = require("./catalog.decorators");
 Object.defineProperty(exports, "CatalogProperty", { enumerable: true, get: function () { return catalog_decorators_1.CatalogProperty; } });
 Object.defineProperty(exports, "CatalogType", { enumerable: true, get: function () { return catalog_decorators_1.CatalogType; } });
@@ -59,6 +59,7 @@ Object.defineProperty(exports, "CONNECTOR_KINDS", { enumerable: true, get: funct
 Object.defineProperty(exports, "isConnectorKind", { enumerable: true, get: function () { return catalog_pipeline_1.isConnectorKind; } });
 Object.defineProperty(exports, "isPipelineStore", { enumerable: true, get: function () { return catalog_pipeline_1.isPipelineStore; } });
 Object.defineProperty(exports, "isTransformLanguage", { enumerable: true, get: function () { return catalog_pipeline_1.isTransformLanguage; } });
+Object.defineProperty(exports, "supportsTransformRevisions", { enumerable: true, get: function () { return catalog_pipeline_1.supportsTransformRevisions; } });
 Object.defineProperty(exports, "isWorkflowEdge", { enumerable: true, get: function () { return catalog_pipeline_1.isWorkflowEdge; } });
 Object.defineProperty(exports, "isWorkflowExecutionMode", { enumerable: true, get: function () { return catalog_pipeline_1.isWorkflowExecutionMode; } });
 Object.defineProperty(exports, "isWorkflowNode", { enumerable: true, get: function () { return catalog_pipeline_1.isWorkflowNode; } });
@@ -102,6 +103,7 @@ Object.defineProperty(exports, "maySearch", { enumerable: true, get: function ()
 Object.defineProperty(exports, "searchCatalog", { enumerable: true, get: function () { return search_1.searchCatalog; } });
 Object.defineProperty(exports, "visibleToPrincipal", { enumerable: true, get: function () { return search_1.visibleToPrincipal; } });
 var catalog_workspace_1 = require("./catalog.workspace");
+Object.defineProperty(exports, "CATALOG_REVISION_LIMIT", { enumerable: true, get: function () { return catalog_workspace_1.CATALOG_REVISION_LIMIT; } });
 Object.defineProperty(exports, "CATALOG_TRACE_OUTCOMES", { enumerable: true, get: function () { return catalog_workspace_1.CATALOG_TRACE_OUTCOMES; } });
 Object.defineProperty(exports, "CATALOG_TRACE_STORE", { enumerable: true, get: function () { return catalog_workspace_1.CATALOG_TRACE_STORE; } });
 Object.defineProperty(exports, "CATALOG_WORKSPACE_STORE", { enumerable: true, get: function () { return catalog_workspace_1.CATALOG_WORKSPACE_STORE; } });
@@ -109,6 +111,7 @@ Object.defineProperty(exports, "embeddedVisualization", { enumerable: true, get:
 Object.defineProperty(exports, "isCatalogTraceOutcome", { enumerable: true, get: function () { return catalog_workspace_1.isCatalogTraceOutcome; } });
 Object.defineProperty(exports, "isTraceStore", { enumerable: true, get: function () { return catalog_workspace_1.isTraceStore; } });
 Object.defineProperty(exports, "isWorkspaceStore", { enumerable: true, get: function () { return catalog_workspace_1.isWorkspaceStore; } });
+Object.defineProperty(exports, "supportsSavedQueryRevisions", { enumerable: true, get: function () { return catalog_workspace_1.supportsSavedQueryRevisions; } });
 Object.defineProperty(exports, "traceOutcomeFilter", { enumerable: true, get: function () { return catalog_workspace_1.traceOutcomeFilter; } });
 var catalog_principal_1 = require("./catalog.principal");
 Object.defineProperty(exports, "CATALOG_PRINCIPAL_RESOLVER", { enumerable: true, get: function () { return catalog_principal_1.CATALOG_PRINCIPAL_RESOLVER; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-catalog",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "A metadata registry for NestJS: object types, properties and relations, derived from your ORM and enriched with decorators.",
   "license": "MIT",
   "author": "Davide Carvalho",