@dudousxd/nestjs-catalog 0.1.0

package/dist/catalog.registry.d.ts

@@ -0,0 +1,44 @@
+import type { EntityClass } from '@mikro-orm/core';
+import { MikroORM } from '@mikro-orm/core';
+import { type OnModuleInit } from '@nestjs/common';
+import { type CatalogModuleOptions } from './catalog.options';
+import type { CatalogOverlayStore } from './catalog.overlay-store';
+import { CatalogRegistry } from './catalog.registry.base';
+import type { CatalogGraph, CatalogObjectTypeDef, CatalogOverlay, CatalogSnapshot } from './catalog.types';
+export declare class MikroOrmCatalogRegistry extends CatalogRegistry implements OnModuleInit {
+    private readonly orm;
+    private readonly options;
+    private readonly overlayStore;
+    private readonly logger;
+    private snapshot;
+    private overlay;
+    private version;
+    /**
+     * Class name -> entity constructor, collected while walking the metadata.
+     *
+     * Kept here rather than looked up on demand because MikroORM's metadata Map
+     * is typed as keyed by `EntityName` (a class), so a `.get(someString)` does
+     * not typecheck even though the runtime keys are class names.
+     */
+    private readonly entityClasses;
+    constructor(orm: MikroORM, options: CatalogModuleOptions, overlayStore: CatalogOverlayStore);
+    onModuleInit(): Promise<void>;
+    getSnapshot(): CatalogSnapshot;
+    getType(name: string): CatalogObjectTypeDef | undefined;
+    /**
+     * The entity constructor behind a catalogued type. Only types that passed
+     * `shouldInclude` are here, so an excluded entity cannot be read through the
+     * generic object endpoint by guessing its name.
+     */
+    getEntityClass(name: string): EntityClass<Record<string, unknown>> | undefined;
+    getGraph(): CatalogGraph;
+    /** Tier-0 edit on a type. Never touches the database. */
+    patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>): Promise<CatalogObjectTypeDef | undefined>;
+    /** Tier-0 edit on a property. Never touches the database. */
+    patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string]): Promise<CatalogObjectTypeDef | undefined>;
+    resetOverlay(): Promise<void>;
+    private persist;
+    private rebuild;
+    private shouldInclude;
+    private buildType;
+}

package/dist/catalog.registry.js

@@ -0,0 +1,359 @@
+"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); }
+};
+var MikroOrmCatalogRegistry_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MikroOrmCatalogRegistry = void 0;
+// Value import, not type-only: Nest resolves this constructor parameter from
+// the emitted `design:paramtypes`, which a type-only import erases.
+const core_1 = require("@mikro-orm/core");
+const common_1 = require("@nestjs/common");
+const catalog_decorators_1 = require("./catalog.decorators");
+const catalog_events_1 = require("./catalog.events");
+const catalog_options_1 = require("./catalog.options");
+const catalog_overlay_store_token_1 = require("./catalog.overlay-store.token");
+const catalog_registry_base_1 = require("./catalog.registry.base");
+const RELATION_KINDS = ['1:1', '1:m', 'm:1', 'm:n'];
+function isRelationKind(kind) {
+    return RELATION_KINDS.includes(kind);
+}
+/** Classify one type name. Returns "unknown" when nothing matches. */
+function classify(raw) {
+    const t = raw.toLowerCase();
+    if (!t)
+        return 'unknown';
+    if (t.includes('uuid'))
+        return 'uuid';
+    // tinyint(1) is how MySQL spells boolean, so it has to beat the "int" test.
+    if (t.includes('bool') || t.startsWith('tinyint(1)'))
+        return 'boolean';
+    if (t.includes('date') || t.includes('time'))
+        return 'date';
+    if (t.includes('int') ||
+        t.includes('float') ||
+        t.includes('double') ||
+        t.includes('decimal') ||
+        t.includes('number') ||
+        t.includes('numeric')) {
+        return 'number';
+    }
+    if (t.includes('json') || t.includes('array'))
+        return 'json';
+    if (t.includes('string') || t.includes('char') || t.includes('text') || t.includes('enum')) {
+        return 'string';
+    }
+    return 'unknown';
+}
+/**
+ * Turn an ORM property into something a UI can switch on.
+ *
+ * Three sources are tried in order, because no single one is reliable. A field
+ * declared `Opt<string>` (MikroORM's optional brand) emits `Object` through
+ * `emitDecoratorMetadata`, so the TypeScript-side type is useless for roughly
+ * half the columns in a real schema — but the SQL column type always knows.
+ * Hence the fallback to `columnTypes`.
+ *
+ * Kept deliberately coarse. This is not reproducing the SQL type system, it is
+ * answering "can I right-align this, and does a date picker make sense".
+ */
+function toScalarType(prop) {
+    const candidates = [prop.runtimeType, prop.type, prop.columnTypes?.[0]].filter((c) => typeof c === 'string' && c.length > 0);
+    for (const candidate of candidates) {
+        const resolved = classify(candidate);
+        // `Object` is what a branded or optional type erases to; it tells us
+        // nothing, so keep looking rather than calling it json.
+        if (resolved !== 'unknown' && candidate.toLowerCase() !== 'object') {
+            return resolved;
+        }
+    }
+    return 'unknown';
+}
+/**
+ * `PriBuyBuyListDetail` -> `Pri Buy Buy List Detail`.
+ *
+ * A guess, and a visibly imperfect one. That is the point: the derived name is
+ * a starting value, and the whole reason the overlay exists is so a human can
+ * correct it in ten seconds without opening an editor.
+ */
+function humanize(name) {
+    const spaced = name
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!spaced)
+        return name;
+    // `id` -> `ID` rather than `Id`: it is the single most common column in any
+    // schema, and getting it wrong is the first thing anyone notices.
+    if (spaced.toLowerCase() === 'id')
+        return 'ID';
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+function pluralize(name) {
+    if (/(s|x|z|ch|sh)$/i.test(name))
+        return `${name}es`;
+    if (/[^aeiou]y$/i.test(name))
+        return `${name.slice(0, -1)}ies`;
+    return `${name}s`;
+}
+let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogRegistry extends catalog_registry_base_1.CatalogRegistry {
+    orm;
+    options;
+    overlayStore;
+    logger = new common_1.Logger(MikroOrmCatalogRegistry_1.name);
+    snapshot = null;
+    overlay = { types: {} };
+    version = 0;
+    /**
+     * Class name -> entity constructor, collected while walking the metadata.
+     *
+     * Kept here rather than looked up on demand because MikroORM's metadata Map
+     * is typed as keyed by `EntityName` (a class), so a `.get(someString)` does
+     * not typecheck even though the runtime keys are class names.
+     */
+    entityClasses = new Map();
+    constructor(orm, options, overlayStore) {
+        super();
+        this.orm = orm;
+        this.options = options;
+        this.overlayStore = overlayStore;
+    }
+    async onModuleInit() {
+        this.overlay = await this.overlayStore.load();
+        this.rebuild();
+        const { types, properties, relations, enrichedTypes } = this.getSnapshot().stats;
+        this.logger.log(`Catalog built: ${types} object types, ${properties} properties, ${relations} relations (${enrichedTypes} enriched)`);
+    }
+    getSnapshot() {
+        if (!this.snapshot)
+            this.rebuild();
+        // rebuild() always assigns, so this is total.
+        return this.snapshot;
+    }
+    getType(name) {
+        return this.getSnapshot().types.find((t) => t.name.toLowerCase() === name.toLowerCase());
+    }
+    /**
+     * The entity constructor behind a catalogued type. Only types that passed
+     * `shouldInclude` are here, so an excluded entity cannot be read through the
+     * generic object endpoint by guessing its name.
+     */
+    getEntityClass(name) {
+        if (!this.snapshot)
+            this.rebuild();
+        return this.entityClasses.get(name);
+    }
+    getGraph() {
+        const snapshot = this.getSnapshot();
+        const known = new Set(snapshot.types.map((t) => t.name));
+        const nodes = snapshot.types.map((t) => ({
+            id: t.name,
+            label: t.displayName,
+            group: t.group,
+            icon: t.icon,
+            propertyCount: t.properties.length,
+            relationCount: t.relations.length,
+        }));
+        // Both ends of a relation are declared, so every link shows up twice. Keep
+        // one edge per unordered pair per name so the graph does not double up.
+        const seen = new Set();
+        const edges = [];
+        for (const type of snapshot.types) {
+            for (const relation of type.relations) {
+                if (!known.has(relation.targetType))
+                    continue;
+                const pair = [type.name, relation.targetType].sort().join('::');
+                const key = `${pair}::${relation.name}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                edges.push({
+                    id: `${type.name}.${relation.name}`,
+                    source: type.name,
+                    target: relation.targetType,
+                    label: relation.displayName,
+                    kind: relation.kind,
+                });
+            }
+        }
+        return { nodes, edges };
+    }
+    /** Tier-0 edit on a type. Never touches the database. */
+    async patchType(typeName, patch) {
+        const type = this.getType(typeName);
+        if (!type)
+            return undefined;
+        const current = this.overlay.types[type.name] ?? {};
+        // `properties` is patched through patchProperty; a type patch must not
+        // clobber it.
+        const { properties: _ignored, ...rest } = patch;
+        this.overlay.types[type.name] = { ...current, ...rest };
+        await this.persist();
+        (0, catalog_events_1.emitCatalog)('type.curated', {
+            typeName: type.name,
+            changed: Object.keys(rest),
+        });
+        return this.getType(type.name);
+    }
+    /** Tier-0 edit on a property. Never touches the database. */
+    async patchProperty(typeName, propertyName, patch) {
+        const type = this.getType(typeName);
+        if (!type)
+            return undefined;
+        const known = type.properties.some((p) => p.name === propertyName) ||
+            type.relations.some((r) => r.name === propertyName);
+        if (!known)
+            return undefined;
+        const currentType = this.overlay.types[type.name] ?? {};
+        const currentProps = currentType.properties ?? {};
+        this.overlay.types[type.name] = {
+            ...currentType,
+            properties: {
+                ...currentProps,
+                [propertyName]: { ...currentProps[propertyName], ...patch },
+            },
+        };
+        await this.persist();
+        (0, catalog_events_1.emitCatalog)('type.curated', {
+            typeName: type.name,
+            property: propertyName,
+            changed: Object.keys(patch),
+        });
+        return this.getType(type.name);
+    }
+    async resetOverlay() {
+        this.overlay = { types: {} };
+        await this.persist();
+    }
+    async persist() {
+        await this.overlayStore.save(this.overlay);
+        this.rebuild();
+    }
+    rebuild() {
+        // `getAll()` returns a Map, not a plain object. Reaching for Object.values
+        // here yields an empty array and a catalog that silently contains nothing.
+        const all = this.orm.getMetadata().getAll();
+        const types = [];
+        this.entityClasses.clear();
+        for (const meta of all.values()) {
+            if (!this.shouldInclude(meta))
+                continue;
+            this.entityClasses.set(meta.className, meta.class);
+            types.push(this.buildType(meta));
+        }
+        types.sort((a, b) => a.group.localeCompare(b.group) || a.displayName.localeCompare(b.displayName));
+        this.version += 1;
+        this.snapshot = {
+            version: this.version,
+            generatedAt: new Date().toISOString(),
+            stats: {
+                types: types.length,
+                properties: types.reduce((n, t) => n + t.properties.length, 0),
+                relations: types.reduce((n, t) => n + t.relations.length, 0),
+                enrichedTypes: types.filter((t) => t.enriched).length,
+            },
+            types,
+        };
+    }
+    shouldInclude(meta) {
+        if (meta.abstract || meta.pivotTable || meta.virtual)
+            return false;
+        if (!meta.className || !meta.tableName)
+            return false;
+        const { include, exclude } = this.options;
+        if (include && include.length > 0 && !include.includes(meta.className)) {
+            return false;
+        }
+        if (exclude?.includes(meta.className))
+            return false;
+        return true;
+    }
+    buildType(meta) {
+        const entityClass = meta.class;
+        const declared = (0, catalog_decorators_1.readTypeOptions)(entityClass);
+        const declaredProps = (0, catalog_decorators_1.readPropertyOptions)(entityClass);
+        const overlay = this.overlay.types[meta.className] ?? {};
+        const overlayProps = overlay.properties ?? {};
+        const properties = [];
+        const relations = [];
+        meta.props.forEach((prop, index) => {
+            // Persisted-only view: `persist: false` marks derived/virtual fields that
+            // have no column to read, and embedded roots duplicate their children.
+            if (prop.persist === false && prop.kind === 'scalar')
+                return;
+            if (prop.kind === 'embedded')
+                return;
+            const fromDecorator = declaredProps[prop.name];
+            const fromOverlay = overlayProps[prop.name];
+            const displayName = fromOverlay?.displayName ?? fromDecorator?.displayName ?? humanize(prop.name);
+            const description = fromOverlay?.description ?? fromDecorator?.description;
+            const hidden = fromOverlay?.hidden ?? fromDecorator?.hidden ?? false;
+            const order = fromOverlay?.order ?? fromDecorator?.order ?? index;
+            if (isRelationKind(prop.kind)) {
+                relations.push({
+                    name: prop.name,
+                    displayName,
+                    description,
+                    kind: prop.kind,
+                    targetType: prop.targetMeta?.className ?? String(prop.type),
+                    localKey: prop.fieldNames?.[0],
+                    nullable: Boolean(prop.nullable),
+                    hidden,
+                    order,
+                });
+                return;
+            }
+            properties.push({
+                name: prop.name,
+                displayName,
+                description,
+                type: toScalarType(prop),
+                columnName: prop.fieldNames?.[0] ?? prop.name,
+                nullable: Boolean(prop.nullable),
+                primary: Boolean(prop.primary),
+                hidden,
+                order,
+                classification: fromOverlay?.classification ?? fromDecorator?.classification,
+                unit: fromOverlay?.unit ?? fromDecorator?.unit,
+                enriched: Boolean(fromDecorator || fromOverlay),
+            });
+        });
+        properties.sort((a, b) => a.order - b.order);
+        relations.sort((a, b) => a.order - b.order);
+        const displayName = overlay.displayName ?? declared.displayName ?? humanize(meta.className);
+        return {
+            name: meta.className,
+            displayName,
+            pluralDisplayName: overlay.pluralDisplayName ?? declared.pluralDisplayName ?? pluralize(displayName),
+            description: overlay.description ?? declared.description,
+            tableName: meta.tableName,
+            icon: overlay.icon ?? declared.icon,
+            group: overlay.group ?? declared.group ?? this.options.defaultGroup ?? 'Ungrouped',
+            titleProperty: overlay.titleProperty ?? declared.titleProperty,
+            primaryKey: meta.primaryKeys ?? [],
+            enriched: Object.keys(declared).length > 0 ||
+                Object.keys(overlay).length > 0 ||
+                properties.some((p) => p.enriched),
+            properties,
+            relations,
+        };
+    }
+};
+exports.MikroOrmCatalogRegistry = MikroOrmCatalogRegistry;
+exports.MikroOrmCatalogRegistry = MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(catalog_options_1.CATALOG_OPTIONS)),
+    __param(2, (0, common_1.Inject)(catalog_overlay_store_token_1.CATALOG_OVERLAY_STORE)),
+    __metadata("design:paramtypes", [core_1.MikroORM, Object, Object])
+], MikroOrmCatalogRegistry);

package/dist/catalog.service.d.ts

@@ -0,0 +1,115 @@
+import { type CatalogModuleOptions } from './catalog.options';
+import { type CatalogQueryRelation, type CatalogQueryResult } from './catalog.query';
+import { CatalogRegistry } from './catalog.registry.base';
+import { type CatalogReadStore, type SnapshotRef } from './catalog.store';
+import type { CatalogGraph, CatalogObjectPage, CatalogObjectQuery, CatalogObjectTypeDef, CatalogOverlay, CatalogSnapshot } from './catalog.types';
+import { type AuditQuery, type CatalogAuditEvent, type CatalogWorkspaceStore, type Dashboard, type DashboardCard, type EmbeddedChart, type EmbeddedDashboard, type SaveQueryInput, type SavedQuery } from './catalog.workspace';
+/**
+ * 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.
+ */
+export declare class CatalogService {
+    private readonly registry;
+    private readonly store;
+    private readonly options;
+    private readonly workspace?;
+    constructor(registry: CatalogRegistry, store: CatalogReadStore, options: CatalogModuleOptions, workspace?: CatalogWorkspaceStore | undefined);
+    private readonly cache;
+    /** The whole model, as data. */
+    getSnapshot(): CatalogSnapshot;
+    getType(name: string): CatalogObjectTypeDef | undefined;
+    /** Nodes and edges, for drawing the model. */
+    getGraph(): CatalogGraph;
+    /** Presentation-only. Never a schema change. */
+    patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>): Promise<CatalogObjectTypeDef | undefined>;
+    patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string]): Promise<CatalogObjectTypeDef | undefined>;
+    /** Drops every runtime edit, where the registry supports it. */
+    resetOverlay(): Promise<void>;
+    /** Columns a generic UI may render: visible, and not a blob. */
+    visibleColumns(type: CatalogObjectTypeDef): import("./catalog.types").CatalogPropertyDef[];
+    readObjects(typeName: string, query: CatalogObjectQuery & {
+        snapshot?: string;
+    }): Promise<CatalogObjectPage>;
+    /** Empty when the store keeps no history. */
+    listSnapshots(typeName: string): Promise<SnapshotRef[]>;
+    /** What the mounted store can do — the screens branch on this. */
+    capabilities(): {
+        query: boolean;
+        snapshots: import("./catalog.store").CatalogSnapshotMode;
+        writable: boolean;
+        timeTravel: boolean;
+        atomicCutover?: boolean;
+        atomicBatchReplace?: boolean;
+        transactional?: boolean;
+    };
+    /** What a query may select from. Empty when the store offers no SQL. */
+    queryRelations(): Promise<CatalogQueryRelation[]>;
+    /**
+     * 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.
+     */
+    runQuery(input: {
+        sql: string;
+        maxRows?: number;
+        /** Reuse a result for this long. Zero (the default) never caches. */
+        cacheTtlSeconds?: number;
+    }): Promise<CatalogQueryResult>;
+    /** Drops every cached result. Exposed so a worker can warm from cold. */
+    clearQueryCache(): void;
+    workspaceAvailable(): boolean;
+    private requireWorkspace;
+    listSavedQueries(): Promise<SavedQuery[]>;
+    getSavedQuery(id: string): Promise<SavedQuery>;
+    saveQuery(input: SaveQueryInput, createdBy: string): Promise<SavedQuery>;
+    updateSavedQuery(id: string, input: Partial<SaveQueryInput>): Promise<SavedQuery>;
+    deleteSavedQuery(id: string): Promise<boolean>;
+    /** Runs a saved query, honouring the TTL it was saved with. */
+    runSavedQuery(id: string, maxRows?: number): Promise<{
+        savedQuery: SavedQuery;
+        result: CatalogQueryResult;
+    }>;
+    listDashboards(): Promise<Dashboard[]>;
+    getDashboard(id: string): Promise<Dashboard>;
+    saveDashboard(input: {
+        name: string;
+        description?: string;
+        cards?: DashboardCard[];
+    }, createdBy: string): Promise<Dashboard>;
+    updateDashboard(id: string, input: Partial<{
+        name: string;
+        description: string;
+        cards: DashboardCard[];
+    }>): Promise<Dashboard>;
+    deleteDashboard(id: string): Promise<boolean>;
+    /** Everything shared, so a consumer can discover what it may render. */
+    listEmbeddable(): Promise<{
+        dashboards: Array<{
+            id: string;
+            name: string;
+            description?: string;
+            charts: number;
+        }>;
+        charts: Array<{
+            id: string;
+            name: string;
+            description?: string;
+            kind: string;
+        }>;
+    }>;
+    /** One chart, rendered. */
+    embedChart(savedQueryId: string, layout?: {
+        width: number;
+        position: number;
+    }): Promise<EmbeddedChart>;
+    /** A whole dashboard, every chart resolved. */
+    embedDashboard(dashboardId: string): Promise<EmbeddedDashboard>;
+    listEvents(query: AuditQuery): Promise<CatalogAuditEvent[]>;
+}