@dudousxd/nestjs-catalog 0.1.0

package/dist/catalog.service.js

@@ -0,0 +1,366 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CatalogService = void 0;
+const common_1 = require("@nestjs/common");
+const catalog_options_1 = require("./catalog.options");
+const catalog_query_1 = require("./catalog.query");
+const catalog_query_cache_1 = require("./catalog.query-cache");
+const catalog_registry_base_1 = require("./catalog.registry.base");
+const catalog_store_1 = require("./catalog.store");
+const catalog_workspace_1 = require("./catalog.workspace");
+const DEFAULT_PAGE_SIZE = 25;
+const DEFAULT_MAX_PAGE_SIZE = 200;
+/**
+ * Reads objects of any catalogued type through one endpoint.
+ *
+ * This layer owns the decisions that must hold no matter where the rows live:
+ * which type names are real, which columns may be returned, how large a page
+ * may be. The store below it only fetches. Keeping the guardrails here means a
+ * new store cannot accidentally relax them — the appeal of a generic read
+ * endpoint is also its whole risk.
+ */
+let CatalogService = class CatalogService {
+    registry;
+    store;
+    options;
+    workspace;
+    constructor(registry, store, options, workspace) {
+        this.registry = registry;
+        this.store = store;
+        this.options = options;
+        this.workspace = workspace;
+    }
+    cache = new catalog_query_cache_1.QueryCache();
+    // ---------------------------------------------------------------------------
+    // The facade.
+    //
+    // Everything the built-in controller does is reachable from this one class, by
+    // class injection — no symbol to import, no second provider to remember. An
+    // app that wants its own routes injects `CatalogService`, writes the
+    // controller it wants, and passes `controller: false` so nothing is mounted
+    // twice. The registry and the store stay available for anyone who needs them,
+    // but nobody should have to reach for them to build an ordinary endpoint.
+    // ---------------------------------------------------------------------------
+    /** The whole model, as data. */
+    getSnapshot() {
+        return this.registry.getSnapshot();
+    }
+    getType(name) {
+        return this.registry.getType(name);
+    }
+    /** Nodes and edges, for drawing the model. */
+    getGraph() {
+        return this.registry.getGraph();
+    }
+    /** Presentation-only. Never a schema change. */
+    patchType(typeName, patch) {
+        return this.registry.patchType(typeName, patch);
+    }
+    patchProperty(typeName, propertyName, patch) {
+        return this.registry.patchProperty(typeName, propertyName, patch);
+    }
+    /** Drops every runtime edit, where the registry supports it. */
+    resetOverlay() {
+        return this.registry.resetOverlay();
+    }
+    /** Columns a generic UI may render: visible, and not a blob. */
+    visibleColumns(type) {
+        return type.properties.filter((p) => !p.hidden && p.type !== 'json');
+    }
+    async readObjects(typeName, query) {
+        const type = this.registry.getType(typeName);
+        if (!type)
+            throw new common_1.NotFoundException(`Unknown object type: ${typeName}`);
+        const maxPageSize = this.options.maxPageSize ?? DEFAULT_MAX_PAGE_SIZE;
+        const size = Math.min(Math.max(Number(query.size) || DEFAULT_PAGE_SIZE, 1), maxPageSize);
+        const page = Math.max(Number(query.page) || 1, 1);
+        const columns = this.visibleColumns(type);
+        if (columns.length === 0) {
+            throw new common_1.BadRequestException(`Object type ${type.name} has no readable columns`);
+        }
+        // Always fetch the primary key: the UI needs a stable row identity even
+        // when the key is hidden from display.
+        const fields = Array.from(new Set([...type.primaryKey, ...columns.map((c) => c.name)]));
+        // Asking for a snapshot a store cannot serve is a caller error, not
+        // something to silently answer with current state — a reader who thinks
+        // they are looking at last Tuesday and is not would rather be told.
+        if (query.snapshot && !this.store.capabilities.timeTravel) {
+            throw new common_1.BadRequestException("This catalog's store keeps no history, so it cannot read a snapshot.");
+        }
+        // Sort is validated here rather than in the store: an unrecognised column
+        // must never reach a query builder, whatever the engine.
+        const sort = columns.some((c) => c.name === query.sort) ? query.sort : undefined;
+        const { rows, total } = await this.store.read(type, fields, {
+            page,
+            size,
+            search: query.search,
+            sort,
+            dir: query.dir === 'desc' ? 'desc' : 'asc',
+            snapshot: query.snapshot,
+        });
+        return {
+            type: type.name,
+            page,
+            size,
+            total,
+            pages: Math.max(Math.ceil(total / size), 1),
+            columns: columns.map((c) => ({
+                name: c.name,
+                displayName: c.displayName,
+                type: c.type,
+                classification: c.classification,
+                unit: c.unit,
+            })),
+            rows,
+        };
+    }
+    /** Empty when the store keeps no history. */
+    async listSnapshots(typeName) {
+        const type = this.registry.getType(typeName);
+        if (!type)
+            throw new common_1.NotFoundException(`Unknown object type: ${typeName}`);
+        if (!this.store.listSnapshots)
+            return [];
+        return this.store.listSnapshots(type);
+    }
+    /** What the mounted store can do — the screens branch on this. */
+    capabilities() {
+        return {
+            ...this.store.capabilities,
+            query: (0, catalog_query_1.isQueryStore)(this.store),
+        };
+    }
+    /** What a query may select from. Empty when the store offers no SQL. */
+    async queryRelations() {
+        if (!(0, catalog_query_1.isQueryStore)(this.store))
+            return [];
+        return this.store.queryRelations();
+    }
+    /**
+     * Run a read-only statement.
+     *
+     * The shape check here produces a readable error; the actual guarantee is the
+     * read-only transaction the store opens, because a keyword denylist is a
+     * guess about a parser and the parser wins eventually.
+     */
+    async runQuery(input) {
+        if (!(0, catalog_query_1.isQueryStore)(this.store)) {
+            throw new common_1.BadRequestException("This catalog's store does not support SQL queries.");
+        }
+        try {
+            (0, catalog_query_1.assertReadOnlyShape)(input.sql);
+        }
+        catch (error) {
+            throw new common_1.BadRequestException(error instanceof Error ? error.message : String(error));
+        }
+        const cap = this.options.maxQueryRows ?? 1_000;
+        const maxRows = Math.min(Math.max(Number(input.maxRows) || cap, 1), cap);
+        // Keyed on the catalog version as well as the SQL: a curation edit that
+        // renames a column must not serve a result computed under the old name.
+        const ttl = input.cacheTtlSeconds ?? 0;
+        const key = catalog_query_cache_1.QueryCache.key(`${input.sql}|${maxRows}`, this.registry.getSnapshot().version);
+        if (ttl > 0) {
+            const hit = this.cache.get(key);
+            if (hit)
+                return { ...hit, cached: true };
+        }
+        const result = await this.store.runQuery({
+            sql: input.sql,
+            maxRows,
+            timeoutMs: this.options.queryTimeoutMs ?? 15_000,
+        });
+        this.cache.set(key, result, ttl);
+        return result;
+    }
+    /** Drops every cached result. Exposed so a worker can warm from cold. */
+    clearQueryCache() {
+        this.cache.clear();
+    }
+    // ---------------------------------------------------------------------------
+    // Workspace: saved queries, dashboards, audit.
+    //
+    // Every method degrades rather than throws when no workspace store is
+    // mounted, because a catalog without one is a legitimate configuration — it
+    // simply has no saved queries, and the screens that need them hide.
+    // ---------------------------------------------------------------------------
+    workspaceAvailable() {
+        return this.workspace !== undefined;
+    }
+    requireWorkspace() {
+        if (!this.workspace) {
+            throw new common_1.BadRequestException('This catalog has no workspace store, so it cannot keep saved queries or dashboards.');
+        }
+        return this.workspace;
+    }
+    listSavedQueries() {
+        return this.workspace ? this.workspace.listSavedQueries() : Promise.resolve([]);
+    }
+    async getSavedQuery(id) {
+        const found = await this.requireWorkspace().getSavedQuery(id);
+        if (!found)
+            throw new common_1.NotFoundException(`No saved query ${id}`);
+        return found;
+    }
+    saveQuery(input, createdBy) {
+        if (!input?.name?.trim()) {
+            throw new common_1.BadRequestException('A saved query needs a name.');
+        }
+        (0, catalog_query_1.assertReadOnlyShape)(input.sql ?? '');
+        return this.requireWorkspace().saveQuery(input, createdBy);
+    }
+    async updateSavedQuery(id, input) {
+        if (input.sql !== undefined)
+            (0, catalog_query_1.assertReadOnlyShape)(input.sql);
+        const updated = await this.requireWorkspace().updateSavedQuery(id, input);
+        if (!updated)
+            throw new common_1.NotFoundException(`No saved query ${id}`);
+        return updated;
+    }
+    deleteSavedQuery(id) {
+        return this.requireWorkspace().deleteSavedQuery(id);
+    }
+    /** Runs a saved query, honouring the TTL it was saved with. */
+    async runSavedQuery(id, maxRows) {
+        const saved = await this.getSavedQuery(id);
+        const result = await this.runQuery({
+            sql: saved.sql,
+            maxRows,
+            cacheTtlSeconds: saved.cacheTtlSeconds,
+        });
+        return { savedQuery: saved, result };
+    }
+    listDashboards() {
+        return this.workspace ? this.workspace.listDashboards() : Promise.resolve([]);
+    }
+    async getDashboard(id) {
+        const found = await this.requireWorkspace().getDashboard(id);
+        if (!found)
+            throw new common_1.NotFoundException(`No dashboard ${id}`);
+        return found;
+    }
+    saveDashboard(input, createdBy) {
+        if (!input?.name?.trim()) {
+            throw new common_1.BadRequestException('A dashboard needs a name.');
+        }
+        return this.requireWorkspace().saveDashboard(input, createdBy);
+    }
+    async updateDashboard(id, input) {
+        const updated = await this.requireWorkspace().updateDashboard(id, input);
+        if (!updated)
+            throw new common_1.NotFoundException(`No dashboard ${id}`);
+        return updated;
+    }
+    deleteDashboard(id) {
+        return this.requireWorkspace().deleteDashboard(id);
+    }
+    // ---------------------------------------------------------------------------
+    // Embed: what another application's frontend gets.
+    //
+    // Only what has been explicitly shared. The alternative — deriving access
+    // from the types a query touches — means parsing SQL to decide a permission,
+    // and a permission that depends on a parser widens silently the first time
+    // the parser meets a query it did not expect.
+    // ---------------------------------------------------------------------------
+    /** Everything shared, so a consumer can discover what it may render. */
+    async listEmbeddable() {
+        const [dashboards, queries] = await Promise.all([
+            this.listDashboards(),
+            this.listSavedQueries(),
+        ]);
+        return {
+            dashboards: dashboards
+                .filter((d) => d.shared)
+                .map((d) => ({
+                id: d.id,
+                name: d.name,
+                description: d.description,
+                charts: d.cards.length,
+            })),
+            charts: queries
+                .filter((q) => q.shared)
+                .map((q) => ({
+                id: q.id,
+                name: q.name,
+                description: q.description,
+                kind: q.visualization.kind,
+            })),
+        };
+    }
+    /** One chart, rendered. */
+    async embedChart(savedQueryId, layout) {
+        const saved = await this.getSavedQuery(savedQueryId);
+        if (!saved.shared) {
+            throw new common_1.ForbiddenException(`"${saved.name}" has not been shared. Mark it shared in the console to make it embeddable.`);
+        }
+        const result = await this.runQuery({
+            sql: saved.sql,
+            cacheTtlSeconds: saved.cacheTtlSeconds,
+        });
+        return {
+            id: saved.id,
+            title: saved.name,
+            description: saved.description,
+            visualization: saved.visualization,
+            layout,
+            columns: result.columns,
+            rows: result.rows,
+            rowCount: result.rowCount,
+            cached: Boolean(result.cached),
+            generatedAt: new Date().toISOString(),
+        };
+    }
+    /** A whole dashboard, every chart resolved. */
+    async embedDashboard(dashboardId) {
+        const dashboard = await this.getDashboard(dashboardId);
+        if (!dashboard.shared) {
+            throw new common_1.ForbiddenException(`"${dashboard.name}" has not been shared.`);
+        }
+        const ordered = [...dashboard.cards].sort((a, b) => a.position - b.position);
+        // Sequential, not parallel: every card is a database query, and a shared
+        // dashboard is exactly the thing a consumer will poll on a timer.
+        const charts = [];
+        for (const card of ordered) {
+            try {
+                charts.push(await this.embedChart(card.savedQueryId, {
+                    width: card.width,
+                    position: card.position,
+                }));
+            }
+            catch {
+                // A card whose query is unshared or broken is skipped rather than
+                // failing the whole dashboard — one bad card should not blank a page.
+            }
+        }
+        return {
+            id: dashboard.id,
+            name: dashboard.name,
+            description: dashboard.description,
+            charts,
+            generatedAt: new Date().toISOString(),
+        };
+    }
+    listEvents(query) {
+        return this.workspace ? this.workspace.listEvents(query) : Promise.resolve([]);
+    }
+};
+exports.CatalogService = CatalogService;
+exports.CatalogService = CatalogService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(catalog_store_1.CATALOG_STORE)),
+    __param(2, (0, common_1.Inject)(catalog_options_1.CATALOG_OPTIONS)),
+    __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, Object, Object, Object])
+], CatalogService);