@dudousxd/nestjs-catalog 0.7.0 → 0.9.0

package/dist/catalog.registry.js

@@ -51,26 +51,6 @@ function isOwningSide(prop, kind) {
         return true;
     return Boolean(prop.owner);
 }
-/**
- * A key both ends of one link agree on, so the graph can draw it once.
- *
- * The owning end names the link — `Mvr.base` — and the inverse end, which knows
- * the owner's property through `mappedBy`, arrives at the same string. That is
- * the whole trick, and it is why `inverseName` is carried on the def at all.
- *
- * The fallback covers metadata that names neither end of the pair: both rows
- * then reduce to the unordered pair plus the property name, which collapses the
- * symmetric case (two `m:n` sides spelled alike) and leaves genuinely different
- * names as two links. Guessing harder than that would mean pairing links by
- * shape, and drawing one line where the schema has two is the worse error.
- */
-function linkKey(holder, relation) {
-    if (relation.owner)
-        return `${holder}.${relation.name}`;
-    if (relation.inverseName)
-        return `${relation.targetType}.${relation.inverseName}`;
-    return `${[holder, relation.targetType].sort().join('::')}::${relation.name}`;
-}
 /** Classify one type name. Returns "unknown" when nothing matches. */
 function classify(raw) {
     const t = raw.toLowerCase();
@@ -198,18 +178,6 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
             this.rebuild();
         return this.entityClasses.get(name);
     }
-    getGraph() {
-        const snapshot = this.getSnapshot();
-        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,
-        }));
-        return { nodes, edges: buildEdges(snapshot.types) };
-    }
     /** Tier-0 edit on a type. Never touches the database. */
     async patchType(typeName, patch) {
         const type = this.getType(typeName);
@@ -253,9 +221,22 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
         });
         return this.getType(type.name);
     }
+    /**
+     * Drop every tier-0 edit, and leave a record that it happened.
+     *
+     * The summary is taken before the overlay is cleared because it is the only
+     * record there will ever be: nothing versions an overlay, so the discarded
+     * values are gone the instant the store is written. See `overlay.reset` in
+     * `catalog.events.ts` for why the payload is a summary and not a copy.
+     *
+     * Emitted after the write, like the two patches above, so the trail says what
+     * happened rather than what was about to.
+     */
     async resetOverlay() {
+        const discarded = summariseOverlay(this.overlay);
         this.overlay = { types: {} };
         await this.persist();
+        (0, catalog_events_1.emitCatalog)('overlay.reset', discarded);
     }
     async persist() {
         await this.overlayStore.save(this.overlay);
@@ -401,47 +382,37 @@ exports.MikroOrmCatalogRegistry = MikroOrmCatalogRegistry = MikroOrmCatalogRegis
     __metadata("design:paramtypes", [core_1.MikroORM, Object, Object])
 ], MikroOrmCatalogRegistry);
 /**
- * The links, as lines to draw.
- *
- * Two rules, and both exist because the naive version of this drew a picture
- * that was wrong in a way nobody would notice:
+ * What a reset is about to destroy, in the shape the trail keeps it.
  *
- * 1. **One edge per link.** A link declared at both ends produces two rows, and
- *    keying the de-duplication on the property name only caught the case where
- *    both ends happened to be spelled alike — so `Mvr.base` plus `Base.mvrs`,
- *    the ordinary shape, drew two lines between the same pair of nodes. See
- *    {@link linkKey}.
- * 2. **Drawn from the end that holds the key**, so the arrow points the way a
- *    join is written. Both ends are collected before either is chosen, because
- *    otherwise the direction depends on which type was discovered first.
+ * Here rather than in `catalog.events.ts` because it reads a `CatalogOverlay`,
+ * and this is the only registry that has one — the payload type is the contract,
+ * this is one producer of it. Pure and taking the overlay as an argument so the
+ * order is forced: a caller has to hold the old overlay to call it, and cannot
+ * accidentally summarise the empty one it just installed.
  *
- * Hidden relations are deliberately still drawn. Hiding is a statement about a
- * table cell; a graph that quietly dropped edges would be a picture nobody could
- * read as complete, which is the only thing a graph is for.
+ * A type entry counts whatever it holds, including an entry that ended up empty.
+ * `buildType` treats a present entry as enrichment on the same terms, and the
+ * honest reading of one is "somebody patched this type" — which is exactly what
+ * the reset undid.
  */
-function buildEdges(types) {
-    const byLink = new Map();
-    for (const type of types) {
-        for (const relation of type.relations) {
-            if (!relation.targetPublished)
-                continue;
-            const key = linkKey(type.name, relation);
-            const seen = byLink.get(key);
-            // Replace only when this row is the owning one and the row already held
-            // is not: anything else keeps the first, so the edge order stays the type
-            // order rather than shuffling with every rebuild.
-            if (seen && (seen.relation.owner || !relation.owner))
-                continue;
-            byLink.set(key, { holder: type.name, relation });
+function summariseOverlay(overlay) {
+    const typeNames = Object.keys(overlay.types);
+    const classifications = [];
+    let properties = 0;
+    for (const typeName of typeNames) {
+        const patched = overlay.types[typeName]?.properties ?? {};
+        for (const [property, patch] of Object.entries(patched)) {
+            properties += 1;
+            const { classification } = patch;
+            // Only a classification that was actually set. An entry that merely
+            // renamed the column carries the key as `undefined`, and listing it would
+            // report a classification lost that nobody had applied.
+            if (classification !== undefined) {
+                classifications.push({ typeName, property, classification });
+            }
         }
     }
-    return [...byLink.values()].map(({ holder, relation }) => ({
-        id: `${holder}.${relation.name}`,
-        source: holder,
-        target: relation.targetType,
-        label: relation.displayName,
-        kind: relation.kind,
-    }));
+    return { typeNames, properties, classifications };
 }
 /**
  * How one field is presented, resolved across the tiers.

package/dist/catalog.service.d.ts

@@ -1,9 +1,11 @@
 import { type CatalogModuleOptions } from './catalog.options';
+import type { CatalogPrincipal } from './catalog.principal';
 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 EmbeddedChartPlacement, type EmbeddedDashboard, type SaveQueryInput, type SavedQuery } from './catalog.workspace';
+import type { CatalogSearchResult } from './search.types';
 /**
  * Reads objects of any catalogued type through one endpoint.
  *
@@ -155,4 +157,19 @@ export declare class CatalogService {
     /** A whole dashboard, every chart resolved. */
     embedDashboard(dashboardId: string): Promise<EmbeddedDashboard>;
     listEvents(query: AuditQuery): Promise<CatalogAuditEvent[]>;
+    /**
+     * Everything matching `term` that this principal may see.
+     *
+     * @param principal the caller, when the host resolved one. **Optional, and its
+     * absence filters nothing** — the declare-and-enforce split written out above
+     * `mayWrite` in `catalog.principal.ts` means this library never resolves a
+     * principal itself. In a deployment with no guard, `GET /catalog` already
+     * hands over the whole snapshot, so search is exactly as open as what is
+     * already there and strictly narrower the moment a principal appears. See
+     * {@link visibleToPrincipal}.
+     */
+    search(term: string, options?: {
+        principal?: CatalogPrincipal;
+        limit?: number;
+    }): Promise<CatalogSearchResult>;
 }

package/dist/catalog.service.js

@@ -21,6 +21,7 @@ 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 search_1 = require("./search");
 const DEFAULT_PAGE_SIZE = 25;
 const DEFAULT_MAX_PAGE_SIZE = 200;
 /**
@@ -519,6 +520,77 @@ let CatalogService = class CatalogService {
     listEvents(query) {
         return this.workspace ? this.workspace.listEvents(query) : Promise.resolve([]);
     }
+    // ---------------------------------------------------------------------------
+    // Search: one term, four kinds of thing.
+    //
+    // **One call that fans out, rather than four the client merges**, and the
+    // reason is not the round trips.
+    //
+    // Half of this is already free: the registry snapshot is in memory, so every
+    // type and every property costs a loop over an object this process is holding
+    // anyway. Only the workspace half touches a store, and it does so as one
+    // `Promise.all` — so the wall clock is the slower of two reads, not four
+    // sequential fetches from a browser. A client that split this to render the
+    // free half a few milliseconds earlier would be buying that with a second
+    // request and a second cache key.
+    //
+    // What actually decides it is that a merged list needs ONE ranking. Four
+    // routes means the client owns the ordering across kinds, which means the
+    // ordering lives in the browser, which means every other consumer of this HTTP
+    // API — and there is meant to be one, that is what `client.ts` is for —
+    // reinvents it slightly differently. And the access filter would have four
+    // places to be forgotten instead of one, which for the thing that decides
+    // whether a caller learns the name of a type they cannot read is not a
+    // trade worth making for a progress spinner.
+    //
+    // The cost, stated because it is real: a deployment whose workspace store is
+    // slow makes the free half wait for it. If that ever bites, the fix is a
+    // `kinds` parameter on this one route, not four routes.
+    // ---------------------------------------------------------------------------
+    /**
+     * Everything matching `term` that this principal may see.
+     *
+     * @param principal the caller, when the host resolved one. **Optional, and its
+     * absence filters nothing** — the declare-and-enforce split written out above
+     * `mayWrite` in `catalog.principal.ts` means this library never resolves a
+     * principal itself. In a deployment with no guard, `GET /catalog` already
+     * hands over the whole snapshot, so search is exactly as open as what is
+     * already there and strictly narrower the moment a principal appears. See
+     * {@link visibleToPrincipal}.
+     */
+    async search(term, options = {}) {
+        const trimmed = (term ?? '').trim();
+        if (!trimmed)
+            return (0, search_1.emptySearch)();
+        // Answered before either store is touched. A principal that may read
+        // nothing should not cost a workspace query to be told so.
+        if (!(0, search_1.maySearch)(options.principal))
+            return (0, search_1.emptySearch)(trimmed);
+        const [savedQueries, dashboards] = await Promise.all([
+            this.listSavedQueries(),
+            this.listDashboards(),
+        ]);
+        return (0, search_1.searchCatalog)({
+            term: trimmed,
+            types: (0, search_1.visibleToPrincipal)(options.principal, this.registry.getSnapshot().types),
+            // Narrowed here rather than handed over whole. `searchCatalog` takes the
+            // fields it ranks and nothing else, so `sql` cannot reach the matcher even
+            // by accident — see `SearchableSavedQuery` for why matching a statement is
+            // the wrong feature rather than a missing one.
+            savedQueries: savedQueries.map((query) => ({
+                id: query.id,
+                name: query.name,
+                description: query.description,
+                folder: query.folder,
+            })),
+            dashboards: dashboards.map((dashboard) => ({
+                id: dashboard.id,
+                name: dashboard.name,
+                description: dashboard.description,
+            })),
+            limit: options.limit,
+        });
+    }
 };
 exports.CatalogService = CatalogService;
 exports.CatalogService = CatalogService = __decorate([

package/dist/client.d.ts

@@ -11,6 +11,7 @@
  */
 export type { AuditQuery, CatalogAuditEvent, Dashboard, DashboardCard, QueryVisualization, SaveQueryInput, SavedQuery, } 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';
 /** What a tier-0 edit to a type may change. */
 export interface TypePatch {
@@ -45,6 +46,16 @@ export interface ObjectQueryParams {
 export declare const catalogRoutes: {
     readonly snapshot: () => string;
     readonly graph: () => string;
+    /**
+     * One term across types, properties, saved queries and dashboards.
+     *
+     * No arguments, unlike `type(name)` and friends: `q` and `limit` are a query
+     * string, and every route here that takes one — `objects`, `events`, `traces`
+     * — leaves it to the caller's HTTP client, because that is the layer that
+     * already knows how to serialise and encode one. `accessRoutes.people` in the
+     * React package does it the other way and is the odd one out.
+     */
+    readonly search: () => string;
     readonly type: (name: string) => string;
     readonly property: (name: string, property: string) => string;
     readonly reset: () => string;

package/dist/client.js

@@ -20,6 +20,16 @@ exports.isWorkflowNodeKind = exports.isWorkflowExecutionMode = exports.workflowR
 exports.catalogRoutes = {
     snapshot: () => '/catalog',
     graph: () => '/catalog/graph',
+    /**
+     * One term across types, properties, saved queries and dashboards.
+     *
+     * No arguments, unlike `type(name)` and friends: `q` and `limit` are a query
+     * string, and every route here that takes one — `objects`, `events`, `traces`
+     * — leaves it to the caller's HTTP client, because that is the layer that
+     * already knows how to serialise and encode one. `accessRoutes.people` in the
+     * React package does it the other way and is the odd one out.
+     */
+    search: () => '/catalog/search',
     type: (name) => `/catalog/types/${encodeURIComponent(name)}`,
     property: (name, property) => `/catalog/types/${encodeURIComponent(name)}/properties/${encodeURIComponent(property)}`,
     reset: () => '/catalog/reset',

package/dist/index.d.ts

@@ -12,6 +12,8 @@ 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 { 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';

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.traceOutcomeFilter = exports.isWorkspaceStore = exports.isTraceStore = exports.isCatalogTraceOutcome = exports.embeddedVisualization = exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = exports.CatalogService = exports.SubprocessTransformRunner = exports.toCsv = exports.QueryCache = exports.workflowRunOrder = exports.workflowGraphHash = 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.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.channelNameFor = exports.catalogEventPhase = 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 = void 0;
+exports.CATALOG_TRACE_OUTCOMES = exports.visibleToPrincipal = exports.searchCatalog = exports.maySearch = 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_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.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.channelNameFor = exports.catalogEventPhase = 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 = 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; } });
@@ -74,6 +74,21 @@ var transform_runner_1 = require("./transform-runner");
 Object.defineProperty(exports, "SubprocessTransformRunner", { enumerable: true, get: function () { return transform_runner_1.SubprocessTransformRunner; } });
 var catalog_service_1 = require("./catalog.service");
 Object.defineProperty(exports, "CatalogService", { enumerable: true, get: function () { return catalog_service_1.CatalogService; } });
+// Search. The result types are on `/client` too, for a browser; these are here
+// because a host that passed `controller: false` and wrote its own routes needs
+// to type the handler, and — more importantly — needs `visibleToPrincipal` and
+// `maySearch` if it calls `searchCatalog` directly rather than going through
+// `CatalogService.search`. Exporting the matcher without them would ship the
+// half that ranks and withhold the half that decides who may see what, which is
+// the exact shape of the gap `index.barrel.spec.ts` was written after.
+var search_1 = require("./search");
+Object.defineProperty(exports, "DEFAULT_SEARCH_LIMIT", { enumerable: true, get: function () { return search_1.DEFAULT_SEARCH_LIMIT; } });
+Object.defineProperty(exports, "MAX_SEARCH_LIMIT", { enumerable: true, get: function () { return search_1.MAX_SEARCH_LIMIT; } });
+Object.defineProperty(exports, "bestMatch", { enumerable: true, get: function () { return search_1.bestMatch; } });
+Object.defineProperty(exports, "emptySearch", { enumerable: true, get: function () { return search_1.emptySearch; } });
+Object.defineProperty(exports, "maySearch", { enumerable: true, get: function () { return search_1.maySearch; } });
+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_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; } });

package/dist/search.d.ts

@@ -0,0 +1,184 @@
+/**
+ * One box that crosses the catalog.
+ *
+ * A catalog with two hundred object types is a catalog where finding anything
+ * means already knowing which screen it lives on — types and properties on the
+ * model screen, saved queries on the query screen, boards on the dashboards
+ * screen — and the thing people actually type is a word they half-remember. This
+ * module is the half of that which has no request in it: given a term, some
+ * types, some saved queries and some dashboards, which rows come back and in
+ * what order.
+ *
+ * Pure on purpose. The ranking is the part a reader has to be able to predict
+ * and the part that must not change by accident, so it is a function with no
+ * store, no principal and no clock in it, and the two things that DO depend on
+ * who is asking — {@link visibleToPrincipal} and the route's scope — sit either
+ * side of it where they can be read.
+ */
+import { type CatalogPrincipal } from './catalog.principal';
+import type { CatalogObjectTypeDef } from './catalog.types';
+import type { CatalogSearchField, CatalogSearchRank, CatalogSearchResult } from './search.types';
+/**
+ * What comes back when nothing was asked for, or when the caller may see
+ * nothing at all.
+ *
+ * A function rather than a shared constant so no two responses can hand out the
+ * same `hits` array — a frozen empty list is safe until somebody downstream
+ * decides an empty result is a fine thing to push a "nothing found" placeholder
+ * onto.
+ *
+ * The two cases are deliberately indistinguishable from outside. "You may see
+ * none of the eleven things that matched" and "eleven things matched, none of
+ * them yours" are the same sentence to a caller, and the second one is the
+ * disclosure.
+ */
+export declare function emptySearch(term?: string): CatalogSearchResult;
+export declare const DEFAULT_SEARCH_LIMIT = 50;
+export declare const MAX_SEARCH_LIMIT = 200;
+interface Candidate {
+    field: CatalogSearchField;
+    value: string | undefined;
+    /**
+     * Whether this field says what the thing is CALLED, as opposed to what
+     * somebody wrote about it. Identifying fields can reach every rank; describing
+     * fields only ever reach `text`.
+     */
+    identifying: boolean;
+}
+/**
+ * The best rank any of these fields can claim for this term, and which field
+ * claimed it.
+ *
+ * Ties go to the field declared first, which is why every call site below lists
+ * `name` before `displayName`: on equal evidence the code name wins, because it
+ * is the stable identity, the string a URL carries, and the one a person who
+ * typed it was almost certainly typing on purpose.
+ *
+ * `term` is expected already lower-cased and trimmed — done once by the caller
+ * rather than per field, since this runs over every property of every type.
+ */
+export declare function bestMatch(term: string, candidates: Candidate[]): {
+    rank: CatalogSearchRank;
+    field: CatalogSearchField;
+} | undefined;
+/**
+ * The catalog as this principal is allowed to see it.
+ *
+ * Two rules, and both are about names rather than values:
+ *
+ * *A type they may not read does not exist here*, and neither do its properties.
+ * A search that answers "there is a type called `PayrollAdjustment`" to somebody
+ * whose `readTypes` excludes it has disclosed the thing they were excluded from,
+ * even though not one row came back.
+ *
+ * *A classified property they do not hold the classification for is dropped, not
+ * blanked.* `readableObjectPage` deletes such a column from a page of rows for
+ * the same reason; here the sensitive part IS the name — `settlement_amount` on
+ * a table called `Dispute` is the disclosure, and a hit saying "there is a
+ * property here you may not see" is worse than no hit, because it also confirms
+ * the guess that produced the search term.
+ *
+ * **An absent principal filters nothing**, and that is not a fail-open. This
+ * library resolves no principal and ships no guard — the split is written out at
+ * length above `mayWrite` in `catalog.principal.ts` — so `undefined` here means
+ * the host wired no guard, and in that deployment `GET /catalog` already hands
+ * the entire snapshot, every type and every property name, to whoever asks.
+ * Search must never be a SOFTER path to something than the routes that exist;
+ * being exactly as soft as the snapshot route, and strictly harder the moment a
+ * principal appears, is the guarantee this can honestly make.
+ *
+ * Hidden properties are kept. `hidden` is a tier-0 display flag any curator can
+ * flip back, it is already in the snapshot, and excluding it would make search
+ * the one place a curator cannot find the property they just hid in order to
+ * un-hide it.
+ */
+export declare function visibleToPrincipal(principal: CatalogPrincipal | undefined, types: CatalogObjectTypeDef[]): CatalogObjectTypeDef[];
+/**
+ * Whether this principal may use the search route at all.
+ *
+ * The route declares `catalog:read` and a host's guard is what enforces it, so
+ * in a correctly wired deployment this can never be false. It is asked anyway
+ * because of what would otherwise be inconsistent: `visibleToPrincipal` drops
+ * every type for a principal without `catalog:read` — `mayRead` checks the scope
+ * first — while the saved queries and dashboards, which have no per-object grant
+ * to check, would sail through. A route that answers "no types, but here are
+ * eleven board names" to somebody who may read nothing is a route whose access
+ * story depends on which half of it you read.
+ */
+export declare function maySearch(principal: CatalogPrincipal | undefined): boolean;
+/**
+ * What a saved query contributes to a search. A subset, not the row: `sql` is
+ * deliberately absent from the input as well as the output.
+ *
+ * Matching on the statement is a tempting feature — "which query touches
+ * `mvr`?" — and it is the wrong one here. It turns a name search into a code
+ * search, so a term like `select` matches everything; the hit it produces cannot
+ * be explained in a row without showing the SQL that justified it; and the row
+ * would then be a fragment of a statement rendered somewhere a statement was
+ * never meant to appear. A host that wants to grep saved SQL wants a different
+ * route with a different name.
+ */
+export interface SearchableSavedQuery {
+    id: string;
+    name: string;
+    description?: string;
+    /** Free-form grouping. Ranked as a `group`, which is what it is. */
+    folder?: string;
+}
+export interface SearchableDashboard {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface SearchInput {
+    term: string;
+    types: CatalogObjectTypeDef[];
+    savedQueries: SearchableSavedQuery[];
+    dashboards: SearchableDashboard[];
+    /** Bounded by {@link MAX_SEARCH_LIMIT} whatever is passed. */
+    limit?: number;
+}
+/**
+ * Search four kinds of thing and return them in one ranked list.
+ *
+ * ---------------------------------------------------------------------------
+ * **Why connectors and transforms are not in here.**
+ *
+ * Not an oversight, and not something to add later without moving something
+ * else first. Connectors and transforms are served by
+ * `@dudousxd/nestjs-catalog-pipeline`, a package this one does not depend on and
+ * should not: `routes.ts` in the React package makes the argument in full, but
+ * the short version is that the catalog library ships no controller for them
+ * because how a deployment exposes the code that reshapes its data is the
+ * deployment's decision, not this library's.
+ *
+ * The access consequence is the deciding one. This route declares
+ * `catalog:read`. A connector carries a connection reference and a
+ * `secretEnvVar` naming where its credential lives, and whatever guard a host
+ * put on its pipeline routes, it was not necessarily this one. Folding
+ * connectors into a `catalog:read` result would quietly re-grant them under a
+ * scope their owner never agreed to — the exact shape of the failure the scope
+ * table at the top of `catalog.controller.ts` exists to prevent.
+ *
+ * So the seam is stated rather than hidden: this searches the registry snapshot
+ * plus the workspace store, which are the two things the catalog module owns. A
+ * console that wants connectors in the same box makes a second call against the
+ * pipeline's own routes, under the pipeline's own guard, and merges two lists —
+ * which is honest about the fact that they are two permissions.
+ * ---------------------------------------------------------------------------
+ *
+ * The order, in full, so it can be argued with:
+ *
+ * 1. rank — `exact`, then `prefix`, then `name`, then `text`;
+ * 2. kind — type, property, saved query, dashboard;
+ * 3. label, then id, lexicographically.
+ *
+ * Rank outranks kind because an exact property match is a better answer than a
+ * type whose description happens to mention the word. Steps 2 and 3 exist so the
+ * result is *total*: a search that returned the same rows in a different order
+ * on the next call would make the top of the list flicker under a debounced
+ * input, and would make every test of this function a test of `Array.sort`
+ * stability.
+ */
+export declare function searchCatalog(input: SearchInput): CatalogSearchResult;
+export {};