@dudousxd/nestjs-catalog 0.1.0

package/dist/catalog.decorators.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CATALOG_PROPERTY_META = exports.CATALOG_TYPE_META = void 0;
+exports.CatalogType = CatalogType;
+exports.CatalogProperty = CatalogProperty;
+exports.readTypeOptions = readTypeOptions;
+exports.readPropertyOptions = readPropertyOptions;
+require("reflect-metadata");
+exports.CATALOG_TYPE_META = Symbol('catalog:type');
+exports.CATALOG_PROPERTY_META = Symbol('catalog:property');
+/**
+ * Declares the semantics the database cannot know: what this entity is called
+ * in the business, which section it belongs to, and what to show when it
+ * appears as a link somewhere else.
+ *
+ * Structure is never declared here — it is read off the ORM. An entity with no
+ * `@CatalogType` still appears in the catalog, just with a name derived from
+ * its class and no group.
+ */
+function CatalogType(options = {}) {
+    return (target) => {
+        const existing = Reflect.getMetadata(exports.CATALOG_TYPE_META, target) ?? {};
+        Reflect.defineMetadata(exports.CATALOG_TYPE_META, { ...existing, ...options }, target);
+    };
+}
+/**
+ * Enriches one property. Everything it sets is tier 0 — the overlay can
+ * override any of it at runtime without a migration, which is precisely why
+ * these live in metadata rather than in the column definition.
+ */
+function CatalogProperty(options = {}) {
+    return (target, propertyKey) => {
+        const ctor = target.constructor;
+        const existing = Reflect.getMetadata(exports.CATALOG_PROPERTY_META, ctor) ?? {};
+        Reflect.defineMetadata(exports.CATALOG_PROPERTY_META, {
+            ...existing,
+            [String(propertyKey)]: { ...existing[String(propertyKey)], ...options },
+        }, ctor);
+    };
+}
+function readTypeOptions(target) {
+    if (typeof target !== 'function')
+        return {};
+    return Reflect.getMetadata(exports.CATALOG_TYPE_META, target) ?? {};
+}
+function readPropertyOptions(target) {
+    if (typeof target !== 'function')
+        return {};
+    return Reflect.getMetadata(exports.CATALOG_PROPERTY_META, target) ?? {};
+}

package/dist/catalog.environment.d.ts

@@ -0,0 +1,442 @@
+/**
+ * Which copy of the world a caller is looking at.
+ *
+ * A catalog that only ever has one copy of everything is a catalog where the
+ * first time a transform runs against real data is the time it runs against the
+ * data people depend on. Environments fix that, and the whole design turns on
+ * one distinction that is easy to blur and expensive to get wrong:
+ *
+ * - **Data never moves between environments.** Not by a button, not by an
+ *   export, not by an accident of a missing `WHERE` clause. Production's rows
+ *   are production's, and dev's rows are whatever dev loaded for itself.
+ * - **Configuration is promoted between them.** The model (object types and the
+ *   labels somebody curated onto them) and the pipeline (connectors, transforms)
+ *   are things you write once, try in dev, and then *release* to production.
+ *
+ * Isolation is therefore physical — one database per environment, so a
+ * statement issued on the dev connection cannot name a production table — and
+ * promotion is a deliberate, previewable release rather than a copy. See
+ * {@link planPromotion} for exactly what crosses and what is refused.
+ *
+ * This is not the same axis as a durable *tenant*. A tenant answers "who
+ * executes this work"; an environment answers "which copy of the world is it
+ * executing against". They are related only in that each environment must get
+ * its own durable keyspace ({@link durableKeyspaceFor}), for the reason spelled
+ * out there.
+ */
+import type { ConnectorKind, TransformLanguage, WorkflowEdge, WorkflowNode } from './catalog.pipeline';
+/**
+ * Where a request declares its environment.
+ *
+ * A header rather than a subdomain or a port, because the whole point is that
+ * one deployment can serve several environments and the choice has to be
+ * visible in the request itself — a proxy rule or a DNS entry is a place the
+ * answer can be wrong without anybody reading it.
+ */
+export declare const CATALOG_ENVIRONMENT_HEADER = "x-catalog-environment";
+/**
+ * The query-parameter spelling, for a browser that cannot set a header — a
+ * `<img>` pointing at an embedded chart, a link somebody pastes into a ticket.
+ *
+ * Deliberately *lower* precedence than the header (see
+ * {@link environmentIdFromRequest}). A query string travels in referrers, logs
+ * and bookmarks; a header does not, so when both are present the one that was
+ * set deliberately by the client wins.
+ */
+export declare const CATALOG_ENVIRONMENT_QUERY = "environment";
+/** An environment's name. Short, lowercase, and safe as a SQL identifier. */
+export type CatalogEnvironmentId = string;
+export declare function isEnvironmentId(value: unknown): value is CatalogEnvironmentId;
+/**
+ * Narrows an id or throws, with the rule in the message.
+ *
+ * Throwing rather than sanitising: an id that had to be repaired is an id that
+ * no longer matches whatever the operator wrote in their configuration, and the
+ * two would disagree about which database the environment lives in.
+ */
+export declare function assertEnvironmentId(value: unknown): CatalogEnvironmentId;
+/**
+ * One copy of the world.
+ *
+ * Everything that distinguishes an environment from its siblings is a physical
+ * address of some kind, which is the point: there is no field here that a
+ * `WHERE` clause could be built out of, because a filter is precisely the sort
+ * of isolation that fails silently the one time somebody forgets it.
+ */
+export interface CatalogEnvironment {
+    id: CatalogEnvironmentId;
+    displayName: string;
+    /**
+     * The physical database this environment's tables live in.
+     *
+     * Not a schema *within* a shared database, and in MySQL those are the same
+     * word anyway — `CREATE SCHEMA` is an alias for `CREATE DATABASE`. What
+     * matters is that the store's table names are fixed (`catalog_object_type`,
+     * `obj_<type>`) and carry no environment in them, so two environments in one
+     * database would collide on every table. Separate databases make the
+     * collision impossible and make MySQL's own `GRANT` the enforcement point.
+     */
+    databaseName: string;
+    /**
+     * The MikroORM context name this environment's connection is registered
+     * under. Feeds `CatalogMikroOrmStoreModule.forRoot({ contextName })`.
+     */
+    contextName: string;
+    /** The durable keyspace. Always derived — see {@link durableKeyspaceFor}. */
+    durableKeyspace: string;
+    /**
+     * How far along the release path this environment sits. Lower is earlier.
+     *
+     * Its only job is to let a promotion refuse to run backwards. Promoting
+     * production's connectors into dev sounds harmless and is not: it would
+     * overwrite the very edits somebody is in the middle of testing, and the
+     * lost work has no version to recover from.
+     */
+    rank: number;
+    /**
+     * Whether this environment refuses changes that did not arrive as a reviewed
+     * promotion.
+     *
+     * True for production. It does not lock the environment — an operator can
+     * still fix something by hand — it means the API demands the explicit
+     * confirmation described on {@link CatalogPromotionApproval} rather than
+     * accepting a plan somebody generated in another tab ten minutes ago.
+     */
+    protected: boolean;
+}
+/**
+ * The caller named no environment.
+ *
+ * Its own class, and never folded into "unknown environment", because the two
+ * have different fixes: this one is a client that has not been taught to say
+ * which world it wants, and the other is a client that named one nobody has
+ * created. A single error message would send everybody to the wrong place.
+ */
+export declare class UnresolvedEnvironmentError extends Error {
+    constructor();
+}
+/** The caller named an environment this deployment does not run. */
+export declare class UnknownEnvironmentError extends Error {
+    readonly requested: string;
+    constructor(requested: string, known: readonly CatalogEnvironmentId[]);
+}
+/**
+ * Reads the requested environment id off a request, without deciding whether it
+ * exists.
+ *
+ * Total and side-effect free so it can be used anywhere a request-like object
+ * is in hand — a guard, a middleware, a test. Returns undefined rather than
+ * throwing, because "nobody said" and "they said something wrong" are different
+ * refusals and the caller is the one that knows which message to produce.
+ */
+export declare function environmentIdFromRequest(request: unknown): string | undefined;
+/**
+ * Turns a request into exactly one environment, or refuses.
+ *
+ * There is no fallback branch in this function and there must never be one.
+ * The failure this prevents is the one that has no symptom: a request that
+ * meant dev and was served by production returns perfectly plausible rows, and
+ * the only way anybody finds out is by noticing later that a number is wrong.
+ */
+export declare function resolveEnvironment(request: unknown, known: readonly CatalogEnvironment[]): CatalogEnvironment;
+/**
+ * The Redis keyspace an environment's durable engine owns.
+ *
+ * Derived rather than configured, and that is the whole safety property. A
+ * deployment that sets `DURABLE_TENANT` by hand per environment has a
+ * copy-paste away from two environments on one keyspace, and the resulting
+ * failure is the one this project has already lived through: every
+ * `BullMQTransport` built on the bare `durable-*` prefix consumes a *single*
+ * `durable-results` queue, so one engine silently eats another's step results,
+ * the originating run's checkpoint stays `pending` forever, and nothing
+ * anywhere logs a word about it.
+ *
+ * The prefix keeps environments of different *services* apart on a shared
+ * Redis; the environment id keeps environments of this service apart from each
+ * other. Both halves are needed: `dev` alone would collide with any other
+ * product's dev engine.
+ */
+export declare function durableKeyspaceFor(environmentId: CatalogEnvironmentId, prefix?: string): string;
+/**
+ * The database name an environment's tables live in.
+ *
+ * Composed here so the same rule is used by the thing that creates the database
+ * and the thing that connects to it. An operator may still override it per
+ * environment; what they may not do is have the two disagree.
+ */
+export declare function catalogDatabaseNameFor(base: string, environmentId: CatalogEnvironmentId): string;
+/**
+ * An audit event, told with the environment it happened in.
+ *
+ * With a database per environment the environment is *implied* by which
+ * database the row sits in, and for a single-environment read that is enough.
+ * It stops being enough the moment anyone asks a governance question across
+ * environments — "everything this person did this week" has to be answerable
+ * without the reader having to remember which of three lists they are looking
+ * at — so the environment is stamped onto every event as it leaves its store.
+ *
+ * Stamped on read rather than stored in a column on purpose: a stored column
+ * can be wrong, because nothing in the database stops a row in the production
+ * table saying `environment: "dev"`. A value derived from which connection the
+ * row was read through cannot be.
+ */
+export interface EnvironmentStampedAuditEvent {
+    environment: CatalogEnvironmentId;
+}
+/** Stamps a batch of events with the environment they were read from. */
+export declare function stampEnvironment<T>(environment: CatalogEnvironmentId, events: readonly T[]): Array<T & EnvironmentStampedAuditEvent>;
+/** What a promotion is allowed to carry. */
+export declare const PROMOTABLE_KINDS: readonly ["objectType", "transform", "workflow", "connector"];
+export type PromotableKind = (typeof PROMOTABLE_KINDS)[number];
+export declare function isPromotableKind(value: unknown): value is PromotableKind;
+/**
+ * Connector fields a promotion never carries, and why each one would be a bug.
+ *
+ * - `state` is where the last run got to — a watermark, a continuation token, a
+ *   last-seen id. Carrying dev's watermark into production tells production it
+ *   has already read everything up to that point, so the next production run
+ *   skips real data and reports success. Carrying production's into dev makes
+ *   dev replay. Either way the corruption is invisible: both runs finish green.
+ * - `lastRunAt` / `lastRunStatus` describe something that happened in the other
+ *   environment. A production connector showing a green run it never performed
+ *   is a lie told by the screen people check first.
+ * - `secretEnvVar` names the credential. It is only a *name*, so promoting it
+ *   leaks nothing — but the name is how the environment finds its own key, and
+ *   production reading `DEV_WAREHOUSE_PASSWORD` is production pointed at dev.
+ * - `enabled` is withheld on create only, so a newly promoted connector arrives
+ *   switched off. Arriving enabled means the first scheduler tick runs, in
+ *   production, code nobody has yet watched run there. On update the target
+ *   keeps whatever it had: re-promoting a transform must not silently
+ *   re-enable a connector an operator deliberately turned off.
+ */
+export declare const PROMOTION_WITHHELD_CONNECTOR_FIELDS: readonly string[];
+/**
+ * A connection is matched, never copied — every field of it is withheld.
+ *
+ * A connection *is* an address and a credential reference, and those are the
+ * two things that most define what an environment is. Promoting dev's
+ * connection config into production would repoint production at the dev
+ * database, and the load that followed would be a successful load of the wrong
+ * data. So promotion requires a connection with the same id to already exist in
+ * the target, configured by whoever owns that environment, and reports its
+ * absence as a blocker rather than creating one.
+ */
+export declare const PROMOTION_WITHHELD_CONNECTION_FIELDS: readonly string[];
+/** A type and its properties, reduced to what a promotion carries. */
+export interface PromotableObjectType {
+    name: string;
+    /**
+     * The application that publishes this type.
+     *
+     * Carried on create and never on update, which is why it is absent from
+     * {@link diffObjectType}'s field list. It has to be carried at all because a
+     * type owned by nobody in the target is a type its publisher would be refused
+     * from publishing into — the store checks ownership by exactly this string.
+     * It must never be *changed* by a promotion, because that would be a way to
+     * take a type away from the application that owns it without anybody
+     * approving an ownership change.
+     */
+    ownerPrincipalId: string;
+    displayName: string;
+    pluralDisplayName: string;
+    description?: string;
+    icon?: string;
+    group: string;
+    titleProperty?: string;
+    primaryKey: string[];
+    properties: Array<{
+        name: string;
+        displayName: string;
+        description?: string;
+        type: string;
+        sourceColumn: string;
+        nullable: boolean;
+        primary: boolean;
+        hidden: boolean;
+        position: number;
+        unit?: string;
+        classification?: string;
+    }>;
+}
+export interface PromotableTransform {
+    id: string;
+    name: string;
+    description?: string;
+    language: TransformLanguage;
+    code: string;
+    /** The source's version, carried for the record only — see {@link planPromotion}. */
+    version: number;
+}
+export interface PromotableConnector {
+    id: string;
+    name: string;
+    description?: string;
+    kind: ConnectorKind;
+    targetType: string;
+    config: Record<string, unknown>;
+    connectionId?: string;
+    transformId?: string;
+    /**
+     * The graph it runs, when it runs one instead of a single transform.
+     *
+     * Carried for the same reason `transformId` is: a connector promoted without
+     * the thing that shapes its rows arrives pointing at nothing. It was missed
+     * once already — workflows were added to the connector while this file was
+     * being written — and the symptom would have been a load failing on its first
+     * scheduled run in the target, which is the worst place to find out.
+     */
+    workflowId?: string;
+    schedule?: string;
+    mode?: 'full' | 'incremental';
+}
+/**
+ * A workflow as promotion sees it.
+ *
+ * `graphHash` rather than `version` is what decides whether two environments
+ * hold the same graph. A version counts edits inside one database, so dev's v7
+ * and production's v7 are unrelated numbers; the hash is over the nodes, their
+ * executable config and the edges in order, so it means the same thing in both
+ * places. Comparing versions across environments would report a difference
+ * every time somebody edited dev twice and production once, and agreement every
+ * time the counts happened to line up.
+ */
+export interface PromotableWorkflow {
+    id: string;
+    name: string;
+    description?: string;
+    targetType: string;
+    graphHash: string;
+    version: number;
+    nodes: WorkflowNode[];
+    edges: WorkflowEdge[];
+}
+/** A connection as promotion sees it: an identity to match against, nothing more. */
+export interface PromotionConnectionRef {
+    id: string;
+    name: string;
+    kind: ConnectorKind;
+}
+/** Everything promotable, read out of one environment. */
+export interface CatalogPromotableSet {
+    objectTypes: PromotableObjectType[];
+    transforms: PromotableTransform[];
+    workflows: PromotableWorkflow[];
+    connectors: PromotableConnector[];
+    connections: PromotionConnectionRef[];
+}
+export type PromotionAction = 'create' | 'update' | 'unchanged';
+/** One field that would change, with both sides shown. */
+export interface PromotionFieldDiff {
+    field: string;
+    from: unknown;
+    to: unknown;
+}
+export interface CatalogPromotionChange {
+    kind: PromotableKind;
+    id: string;
+    name: string;
+    action: PromotionAction;
+    fields: PromotionFieldDiff[];
+    /** Things a reviewer should read before approving. Never fatal. */
+    notes: string[];
+}
+/**
+ * Something that makes the plan unappliable.
+ *
+ * A blocker is not a warning. The plan is reported in full so a reviewer can
+ * see everything that *would* happen, and then refused, because a promotion
+ * that applies the half it can and skips the half it cannot leaves the target
+ * in a state neither environment ever had.
+ */
+export interface CatalogPromotionBlocker {
+    kind: PromotableKind | 'connection';
+    id: string;
+    name: string;
+    reason: string;
+}
+/** Something the promotion deliberately left behind, named so the preview says so. */
+export interface CatalogPromotionWithheld {
+    kind: PromotableKind | 'connection';
+    id: string;
+    name: string;
+    fields: readonly string[];
+    why: string;
+}
+export interface CatalogPromotionPlan {
+    from: CatalogEnvironmentId;
+    to: CatalogEnvironmentId;
+    createdAt: string;
+    changes: CatalogPromotionChange[];
+    blockers: CatalogPromotionBlocker[];
+    withheld: CatalogPromotionWithheld[];
+    /**
+     * A hash of exactly what this plan would do.
+     *
+     * The point of a preview is that somebody read it. Without a fingerprint the
+     * apply call is a fresh promotion that happens to have been preceded by a
+     * preview, and anything that changed in between — a colleague editing the
+     * transform, a connector deleted — goes in unreviewed. The apply endpoint
+     * demands this value back, recomputes the plan, and refuses if the two
+     * differ. That is what turns "we show a diff" into "you approved this diff".
+     */
+    fingerprint: string;
+}
+/**
+ * The audit event name a completed promotion records.
+ *
+ * Deliberately *not* added to `CATALOG_EVENTS` and not emitted through
+ * `emitCatalog`. That channel is for things the library itself does during a
+ * load, and it is consumed by a recorder that writes wherever its workspace
+ * store points — which, with environments in play, is whichever environment
+ * happens to be in scope. A promotion is the one act that is genuinely about
+ * two environments at once, so its record is written directly into the target's
+ * audit table by the code that performed it, where there is no question about
+ * which environment the row belongs to.
+ */
+export declare const PROMOTION_AUDIT_EVENT = "promotion.applied";
+/** What an apply call must present to prove which plan was approved. */
+export interface CatalogPromotionApproval {
+    fingerprint: string;
+    /** Free text the operator typed. Recorded in the audit trail, never parsed. */
+    reason?: string;
+}
+/**
+ * Compute what promoting `source` into `target` would do.
+ *
+ * Pure, and pure on purpose: this is the function whose output a person reads
+ * before agreeing to change production, so it must be runnable against two
+ * plain objects, in a test, with no database anywhere near it.
+ *
+ * **Additive.** Nothing in the target that is absent from the source is
+ * touched, let alone deleted. A promotion is a release of the things somebody
+ * built, not a mirror of one environment onto another — and a production
+ * connector that exists for a reason dev knows nothing about must survive a
+ * colleague promoting an unrelated transform.
+ *
+ * **Version numbers do not cross.** A transform's `version` counts the edits
+ * made *in the environment it lives in*. Copying dev's version onto production
+ * would make production's own history unreadable — v7 following v3 with nothing
+ * in between — so the target bumps its own, and the source version is carried
+ * in the change note instead, which is what actually answers "which code is
+ * this".
+ */
+export declare function planPromotion(input: {
+    from: CatalogEnvironmentId;
+    to: CatalogEnvironmentId;
+    source: CatalogPromotableSet;
+    target: CatalogPromotableSet;
+    /**
+     * Restrict the promotion to specific things, by `kind:id`
+     * (`transform:abc`, `objectType:Mvr`). Undefined means everything promotable.
+     *
+     * Worth having rather than an all-or-nothing release: dev accumulates
+     * experiments nobody intends to ship, and a promotion that could only carry
+     * every one of them would be a promotion nobody dares run.
+     */
+    select?: readonly string[];
+    now?: () => Date;
+}): CatalogPromotionPlan;
+/** Whether a plan may be applied at all. */
+export declare function isPromotable(plan: CatalogPromotionPlan): boolean;
+/** The changes that actually do something. Used by both the apply and the summary. */
+export declare function effectiveChanges(plan: CatalogPromotionPlan): CatalogPromotionChange[];