@dudousxd/nestjs-catalog 0.7.0 → 0.8.0

package/dist/catalog.controller.d.ts

@@ -42,6 +42,12 @@ import { type Type } from '@nestjs/common';
  * every label one request at a time. Requiring admin would deny nothing and
  * would push a routine console action into the scope that manages principals.
  *
+ * **`GET search` is the one read here that looks at the principal.** Its scope
+ * is the unsurprising `catalog:read`; what is surprising is that it filters, in
+ * a library whose read routes deliberately do not. The reason it has to is on
+ * the route itself, and it is short: a host can wrap a read whose subject it
+ * knows, and cannot wrap one whose result set is chosen by a stranger's typing.
+ *
  * One consequence is worth stating rather than leaving to be discovered:
  * `shared` rides on the dashboard write routes, so `catalog:curate` carries the
  * power to hand a board to an outside application. That is not an oversight —

package/dist/catalog.controller.js

@@ -62,6 +62,12 @@ const catalog_workspace_1 = require("./catalog.workspace");
  * every label one request at a time. Requiring admin would deny nothing and
  * would push a routine console action into the scope that manages principals.
  *
+ * **`GET search` is the one read here that looks at the principal.** Its scope
+ * is the unsurprising `catalog:read`; what is surprising is that it filters, in
+ * a library whose read routes deliberately do not. The reason it has to is on
+ * the route itself, and it is short: a host can wrap a read whose subject it
+ * knows, and cannot wrap one whose result set is chosen by a stranger's typing.
+ *
  * One consequence is worth stating rather than leaving to be discovered:
  * `shared` rides on the dashboard write routes, so `catalog:curate` carries the
  * power to hand a board to an outside application. That is not an oversight —
@@ -95,6 +101,44 @@ function createCatalogController(path, guards, decorators = []) {
         graph() {
             return this.registry.getGraph();
         }
+        /**
+         * One term, across object types, properties, saved queries and dashboards.
+         *
+         * `catalog:read`, which is the scope of the four routes this is a shortcut
+         * to — `GET /catalog`, `GET saved-queries`, `GET dashboards` — and
+         * deliberately not narrower. A discovery route gated harder than the things
+         * it discovers is a route nobody can use; one gated softer is a way around
+         * them. Nothing here reaches a row of data or a statement: it returns names,
+         * labels and ids, which is a strict subset of what `GET /catalog` already
+         * hands the same caller.
+         *
+         * **The principal is passed, and this is one of two routes on this
+         * controller that filter by it.** The library's usual position is that reads
+         * apply no grants and a host wraps them — stated at length above `mayWrite`
+         * in `catalog.principal.ts`, and true of `GET objects/:name` right below.
+         * That position does not survive contact with a search box. A host can wrap
+         * `readObjects` because it knows the type being read and can decide; it
+         * cannot wrap this, because the whole result set is chosen by what somebody
+         * typed and the thing that must not come back is a NAME, which no wrapper
+         * downstream can distinguish from a name that was fine. Filtering has to
+         * happen where the candidates are enumerated, so it happens in
+         * `CatalogService.search`, and `visibleToPrincipal` is where to read the
+         * rules.
+         *
+         * The `@Req()` here is the same shape `actorOf` reads below, and for the
+         * same reason: a guard the host wrote put it there, and when no guard did,
+         * `undefined` arrives and nothing is filtered — see the service.
+         *
+         * Declared before every route carrying a parameter in the first segment,
+         * which today is none of them, so this is defensive rather than load-bearing.
+         * `events/traces` further down is the case where it is not.
+         */
+        search(q, limit, request) {
+            return this.service.search(q ?? '', {
+                principal: request?.principal,
+                limit: limit ? Number(limit) : undefined,
+            });
+        }
         type(name) {
             const type = this.registry.getType(name);
             if (!type)
@@ -347,6 +391,16 @@ function createCatalogController(path, guards, decorators = []) {
         __metadata("design:paramtypes", []),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "graph", null);
+    __decorate([
+        (0, common_1.Get)('search'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
+        __param(0, (0, common_1.Query)('q')),
+        __param(1, (0, common_1.Query)('limit')),
+        __param(2, (0, common_1.Req)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String, String, Object]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "search", null);
     __decorate([
         (0, common_1.Get)('types/:name'),
         (0, catalog_route_auth_1.RequireScopes)('catalog:read'),

package/dist/catalog.registry.base.d.ts

@@ -1,4 +1,37 @@
 import type { CatalogGraph, CatalogObjectTypeDef, CatalogOverlay, CatalogSnapshot } from './catalog.types';
+/**
+ * The ontology, as nodes and lines. **The one implementation of the edge rule.**
+ *
+ * Three rules, and all three exist because the naive version of each drew a
+ * picture that was wrong in a way nobody would notice:
+ *
+ * 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 of a foreign key, drew two lines between the same pair
+ *    of nodes. See {@link linkKey} for how the two rows are recognised as one.
+ * 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.
+ * 3. **No edge to a node that is not here.** An edge promises a node the reader
+ *    can open, and a target this catalog does not hold has none.
+ *
+ * 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.
+ *
+ * WHY IT LIVES HERE, ON THE BASE CLASS'S OWN MODULE
+ * -------------------------------------------------
+ * Both registries had a copy — one derives the model from ORM metadata, the
+ * other reads it out of the database — in different packages, each carrying a
+ * comment asking the next person to change them together. A comment is not a
+ * mechanism, and a divergence here would be invisible: the two screens would
+ * simply disagree about how many links exist, and the copy that regressed would
+ * look exactly like the original bug (two edges per foreign key). The graph is a
+ * pure function of the snapshot, which is the one thing every registry already
+ * has to produce, so there was never anything for a subclass to decide.
+ */
+export declare function buildCatalogGraph(types: CatalogObjectTypeDef[]): CatalogGraph;
 /**
  * What the catalog knows about your types, however it came to know it.
  *
@@ -13,7 +46,19 @@ import type { CatalogGraph, CatalogObjectTypeDef, CatalogOverlay, CatalogSnapsho
 export declare abstract class CatalogRegistry {
     abstract getSnapshot(): CatalogSnapshot;
     abstract getType(name: string): CatalogObjectTypeDef | undefined;
-    abstract getGraph(): CatalogGraph;
+    /**
+     * The ontology, drawn. Concrete, and the only implementation either registry
+     * runs.
+     *
+     * Not abstract because nothing about it varies: every edge and every node is
+     * read off the snapshot, and the snapshot is the abstract thing. The two
+     * registries did each override it with the same forty lines, which is how the
+     * edge rule came to exist twice in two packages — the failure this being a
+     * concrete method prevents. Where a registry *delegates* rather than derives
+     * (`RoutingCatalogRegistry` hands the whole call to whichever environment the
+     * request named) overriding is still right; deriving it a second time is not.
+     */
+    getGraph(): CatalogGraph;
     /** Presentation-only edits. Never a schema change. */
     abstract patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>): Promise<CatalogObjectTypeDef | undefined>;
     abstract patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string]): Promise<CatalogObjectTypeDef | undefined>;

package/dist/catalog.registry.base.js

@@ -1,6 +1,93 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CatalogRegistry = void 0;
+exports.buildCatalogGraph = buildCatalogGraph;
+/**
+ * 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}`;
+}
+/**
+ * The ontology, as nodes and lines. **The one implementation of the edge rule.**
+ *
+ * Three rules, and all three exist because the naive version of each drew a
+ * picture that was wrong in a way nobody would notice:
+ *
+ * 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 of a foreign key, drew two lines between the same pair
+ *    of nodes. See {@link linkKey} for how the two rows are recognised as one.
+ * 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.
+ * 3. **No edge to a node that is not here.** An edge promises a node the reader
+ *    can open, and a target this catalog does not hold has none.
+ *
+ * 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.
+ *
+ * WHY IT LIVES HERE, ON THE BASE CLASS'S OWN MODULE
+ * -------------------------------------------------
+ * Both registries had a copy — one derives the model from ORM metadata, the
+ * other reads it out of the database — in different packages, each carrying a
+ * comment asking the next person to change them together. A comment is not a
+ * mechanism, and a divergence here would be invisible: the two screens would
+ * simply disagree about how many links exist, and the copy that regressed would
+ * look exactly like the original bug (two edges per foreign key). The graph is a
+ * pure function of the snapshot, which is the one thing every registry already
+ * has to produce, so there was never anything for a subclass to decide.
+ */
+function buildCatalogGraph(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 });
+        }
+    }
+    return {
+        nodes: types.map((t) => ({
+            id: t.name,
+            label: t.displayName,
+            group: t.group,
+            icon: t.icon,
+            propertyCount: t.properties.length,
+            relationCount: t.relations.length,
+        })),
+        edges: [...byLink.values()].map(({ holder, relation }) => ({
+            id: `${holder}.${relation.name}`,
+            source: holder,
+            target: relation.targetType,
+            label: relation.displayName,
+            kind: relation.kind,
+        })),
+    };
+}
 /**
  * What the catalog knows about your types, however it came to know it.
  *
@@ -13,5 +100,20 @@ exports.CatalogRegistry = void 0;
  * data it was handed. Everything above this line works the same either way.
  */
 class CatalogRegistry {
+    /**
+     * The ontology, drawn. Concrete, and the only implementation either registry
+     * runs.
+     *
+     * Not abstract because nothing about it varies: every edge and every node is
+     * read off the snapshot, and the snapshot is the abstract thing. The two
+     * registries did each override it with the same forty lines, which is how the
+     * edge rule came to exist twice in two packages — the failure this being a
+     * concrete method prevents. Where a registry *delegates* rather than derives
+     * (`RoutingCatalogRegistry` hands the whole call to whichever environment the
+     * request named) overriding is still right; deriving it a second time is not.
+     */
+    getGraph() {
+        return buildCatalogGraph(this.getSnapshot().types);
+    }
 }
 exports.CatalogRegistry = CatalogRegistry;

package/dist/catalog.registry.d.ts

@@ -4,7 +4,7 @@ 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';
+import type { CatalogObjectTypeDef, CatalogOverlay, CatalogSnapshot } from './catalog.types';
 export declare class MikroOrmCatalogRegistry extends CatalogRegistry implements OnModuleInit {
     private readonly orm;
     private readonly options;
@@ -31,7 +31,6 @@ export declare class MikroOrmCatalogRegistry extends CatalogRegistry implements
      * 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. */

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);
@@ -400,49 +368,6 @@ exports.MikroOrmCatalogRegistry = MikroOrmCatalogRegistry = MikroOrmCatalogRegis
     __param(2, (0, common_1.Inject)(catalog_overlay_store_token_1.CATALOG_OVERLAY_STORE)),
     __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:
- *
- * 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.
- *
- * 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.
- */
-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 });
-        }
-    }
-    return [...byLink.values()].map(({ holder, relation }) => ({
-        id: `${holder}.${relation.name}`,
-        source: holder,
-        target: relation.targetType,
-        label: relation.displayName,
-        kind: relation.kind,
-    }));
-}
 /**
  * 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 {};

package/dist/search.js

@@ -0,0 +1,345 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SEARCH_LIMIT = exports.DEFAULT_SEARCH_LIMIT = void 0;
+exports.emptySearch = emptySearch;
+exports.bestMatch = bestMatch;
+exports.visibleToPrincipal = visibleToPrincipal;
+exports.maySearch = maySearch;
+exports.searchCatalog = searchCatalog;
+const catalog_principal_1 = require("./catalog.principal");
+/**
+ * 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.
+ */
+function emptySearch(term = '') {
+    return { term, total: 0, truncated: false, hits: [] };
+}
+exports.DEFAULT_SEARCH_LIMIT = 50;
+exports.MAX_SEARCH_LIMIT = 200;
+/**
+ * Strongest first. The numbers are only ever compared, never shown — the wire
+ * carries the name, so a client can render "exact" without knowing this table.
+ */
+const RANK_ORDER = {
+    exact: 0,
+    prefix: 1,
+    name: 2,
+    text: 3,
+};
+/**
+ * The tie-break after rank, and it is a claim about what people search for.
+ *
+ * A type is the thing somebody is usually looking for; a property only exists
+ * inside one; a saved query and a board are things somebody made later. Equal
+ * evidence, so the more likely intent wins. It is stated as a table rather than
+ * left to array order because the order results are *built* in is an
+ * implementation detail and this is not.
+ */
+const KIND_ORDER = {
+    objectType: 0,
+    property: 1,
+    savedQuery: 2,
+    dashboard: 3,
+};
+/**
+ * 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.
+ */
+function bestMatch(term, candidates) {
+    let best;
+    for (const candidate of candidates) {
+        const rank = rankOne(term, candidate);
+        if (rank && (!best || RANK_ORDER[rank] < RANK_ORDER[best.rank])) {
+            best = { rank, field: candidate.field };
+            // `exact` is the ceiling, so nothing later can beat it and the remaining
+            // fields need not be read at all.
+            if (rank === 'exact')
+                return best;
+        }
+    }
+    return best;
+}
+/** How well one field matches, on its own. The four tiers, and nothing else. */
+function rankOne(term, candidate) {
+    const value = candidate.value?.trim().toLowerCase();
+    if (!value)
+        return undefined;
+    if (!candidate.identifying) {
+        // Describing fields get one rank and no gradations. See the note on
+        // `CatalogSearchRank`: "the description opens with your word" is not
+        // evidence of anything.
+        return value.includes(term) ? 'text' : undefined;
+    }
+    if (value === term)
+        return 'exact';
+    if (value.startsWith(term))
+        return 'prefix';
+    if (value.includes(term))
+        return 'name';
+    return 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.
+ */
+function visibleToPrincipal(principal, types) {
+    if (!principal)
+        return types;
+    const visible = [];
+    for (const type of types) {
+        if (!(0, catalog_principal_1.mayRead)(principal, type.name))
+            continue;
+        const properties = type.properties.filter((property) => (0, catalog_principal_1.maySeeClassification)(principal, property.classification));
+        // Rebuilt only when something was actually dropped, so the common case
+        // hands back the registry's own object rather than a copy of it per search.
+        visible.push(properties.length === type.properties.length ? type : { ...type, properties });
+    }
+    return visible;
+}
+/**
+ * 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.
+ */
+function maySearch(principal) {
+    if (!principal)
+        return true;
+    return (0, catalog_principal_1.hasScope)(principal, 'catalog:read');
+}
+/**
+ * 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.
+ */
+function searchCatalog(input) {
+    const term = input.term.trim().toLowerCase();
+    // An empty box is not an error. A search screen mounts empty, and a 400 on
+    // mount is a red panel where a prompt should be.
+    if (!term)
+        return emptySearch();
+    const limit = Math.min(Math.max(Math.trunc(Number(input.limit) || exports.DEFAULT_SEARCH_LIMIT), 1), exports.MAX_SEARCH_LIMIT);
+    // One flat list, built per kind and ranked as a whole. Building it per kind
+    // and concatenating would put the kind order ahead of the rank, which is
+    // exactly backwards — see the order stated above.
+    const hits = [
+        ...input.types.flatMap((type) => hitsForType(term, type)),
+        ...input.savedQueries.flatMap((query) => hitsForSavedQuery(term, query)),
+        ...input.dashboards.flatMap((dashboard) => hitsForDashboard(term, dashboard)),
+    ];
+    hits.sort(compareHits);
+    return {
+        term,
+        // Counted before the cut, so a UI can say "50 of 312" — and counted after
+        // the caller's own types were filtered out upstream, which is the half that
+        // matters. See `CatalogSearchResult.total`.
+        total: hits.length,
+        truncated: hits.length > limit,
+        hits: hits.slice(0, limit),
+    };
+}
+/** The type itself, then every property on it. Zero, one or many. */
+function hitsForType(term, type) {
+    const hits = [];
+    const typeMatch = bestMatch(term, [
+        { field: 'name', value: type.name, identifying: true },
+        { field: 'displayName', value: type.displayName, identifying: true },
+        // The plural is an identifying field too — somebody typing "vehicles" means
+        // the type — but it is reported as `displayName`, because "matched:
+        // pluralDisplayName" is a distinction no reader of a search row wants.
+        { field: 'displayName', value: type.pluralDisplayName, identifying: true },
+        { field: 'description', value: type.description, identifying: false },
+        { field: 'group', value: type.group, identifying: false },
+    ]);
+    if (typeMatch) {
+        hits.push({
+            kind: 'objectType',
+            id: type.name,
+            label: type.displayName || type.name,
+            typeName: type.name,
+            detail: type.group || undefined,
+            ...typeMatch,
+        });
+    }
+    for (const property of type.properties) {
+        const match = bestMatch(term, [
+            { field: 'name', value: property.name, identifying: true },
+            { field: 'displayName', value: property.displayName, identifying: true },
+            { field: 'description', value: property.description, identifying: false },
+            { field: 'unit', value: property.unit, identifying: false },
+        ]);
+        if (!match)
+            continue;
+        hits.push({
+            kind: 'property',
+            id: property.name,
+            label: property.displayName || property.name,
+            typeName: type.name,
+            detail: property.unit ? `${property.type} · ${property.unit}` : property.type,
+            ...match,
+        });
+    }
+    return hits;
+}
+function hitsForSavedQuery(term, query) {
+    const match = bestMatch(term, [
+        // A saved query has no code name, so `name` is its one identifying field —
+        // listed first, matching the tie-break rule everywhere else.
+        { field: 'name', value: query.name, identifying: true },
+        { field: 'description', value: query.description, identifying: false },
+        { field: 'group', value: query.folder, identifying: false },
+    ]);
+    if (!match)
+        return [];
+    return [
+        {
+            kind: 'savedQuery',
+            id: query.id,
+            label: query.name,
+            detail: query.folder || undefined,
+            ...match,
+        },
+    ];
+}
+function hitsForDashboard(term, dashboard) {
+    const match = bestMatch(term, [
+        { field: 'name', value: dashboard.name, identifying: true },
+        { field: 'description', value: dashboard.description, identifying: false },
+    ]);
+    if (!match)
+        return [];
+    return [{ kind: 'dashboard', id: dashboard.id, label: dashboard.name, ...match }];
+}
+function compareHits(a, b) {
+    const byRank = RANK_ORDER[a.rank] - RANK_ORDER[b.rank];
+    if (byRank !== 0)
+        return byRank;
+    const byKind = KIND_ORDER[a.kind] - KIND_ORDER[b.kind];
+    if (byKind !== 0)
+        return byKind;
+    // Plain comparison rather than `localeCompare`: the order has to be the same
+    // in a test, on a developer's machine and in a container with no ICU data,
+    // and a locale-aware collation is the one thing here that differs between all
+    // three.
+    if (a.label !== b.label)
+        return a.label < b.label ? -1 : 1;
+    if (a.id !== b.id)
+        return a.id < b.id ? -1 : 1;
+    // Two properties of the same name on different types. Nothing else can
+    // separate them, and leaving it to sort stability would make the order depend
+    // on the registry's iteration order.
+    //
+    // Zero when even that is equal, rather than a constant 1: a comparator that
+    // reports `a > b` and `b > a` for the same pair is not an ordering, and some
+    // sort implementations are entitled to do anything at all with one.
+    const aType = a.typeName ?? '';
+    const bType = b.typeName ?? '';
+    if (aType === bType)
+        return 0;
+    return aType < bType ? -1 : 1;
+}

package/dist/search.types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * What one search across the catalog gives back.
+ *
+ * A separate file from `search.ts` so `client.ts` can re-export these without
+ * dragging the matcher into a browser bundle. The shapes are the contract — a
+ * host writing its own search box needs them as much as it needs the path.
+ *
+ * **Rows, not objects.** Every hit carries what it takes to draw a line and
+ * follow it, and nothing else: no `sql`, no property list, no card layout. That
+ * is not a size optimisation. A search route is the one endpoint whose result
+ * set is chosen by a stranger's typing, so it is the endpoint where "we returned
+ * a bit more than the screen needed" turns into a disclosure nobody reviewed. A
+ * caller that wants the whole saved query asks `GET saved-queries/:id`, which is
+ * a route somebody thought about.
+ */
+/**
+ * What kind of thing was found.
+ *
+ * Four, and the omissions are deliberate — see the block above `searchCatalog`
+ * in `search.ts` for why connectors and transforms are not here and cannot be
+ * without changing which package owns their access model.
+ */
+export type CatalogSearchKind = 'objectType' | 'property' | 'savedQuery' | 'dashboard';
+/**
+ * How well it matched, strongest first. Four values rather than a number,
+ * because a score is only useful if a reader can predict it, and nobody has ever
+ * been able to predict `0.6231`.
+ *
+ * - `exact` — an identifying field IS the term.
+ * - `prefix` — an identifying field starts with it.
+ * - `name` — an identifying field contains it somewhere.
+ * - `text` — a describing field contains it.
+ *
+ * Identifying means `name` or `displayName`: what the thing is called. Describing
+ * means `description`, `group`, `unit`: what somebody wrote about it. The split
+ * is the whole ranking. Within a describing field no distinction is made between
+ * "starts with" and "contains", because a description that happens to open with
+ * your word is not a better answer than one that mentions it in the middle, and
+ * pretending otherwise is where an unpredictable score starts.
+ */
+export type CatalogSearchRank = 'exact' | 'prefix' | 'name' | 'text';
+/** Which field the term was found in — the "why" on every row. */
+export type CatalogSearchField = 'name' | 'displayName' | 'description' | 'group' | 'unit';
+export interface CatalogSearchHit {
+    kind: CatalogSearchKind;
+    /**
+     * What identifies it within its kind: the type name, the property name, the
+     * saved query's or dashboard's id.
+     *
+     * Not unique across kinds on its own — a property called `status` on two types
+     * is two hits with the same `id` — so anything keying on a hit keys on
+     * `kind`, `typeName` and `id` together.
+     */
+    id: string;
+    /** What to show. The display name where there is one, the code name otherwise. */
+    label: string;
+    /**
+     * The object type this result belongs to: itself for an `objectType`, its
+     * owner for a `property`, absent for a saved query or a dashboard.
+     *
+     * Set on the type as well as the property so a client navigating to the model
+     * screen writes `hit.typeName && explorerHref(hit.typeName)` once, rather than
+     * a branch per kind that will be wrong the first time a kind is added.
+     */
+    typeName?: string;
+    /**
+     * One short line of context: the group for a type, the scalar type and unit
+     * for a property, the folder for a saved query.
+     *
+     * Structural, never a snippet of the description. A snippet would have to be
+     * cut somewhere, and a description cut mid-sentence is how a classified
+     * meaning ends up half-rendered in a dropdown; `field` already says the match
+     * was in the description, and the row it links to shows the whole of it.
+     */
+    detail?: string;
+    rank: CatalogSearchRank;
+    field: CatalogSearchField;
+}
+export interface CatalogSearchResult {
+    /** The term as it was searched, trimmed. Echoed so a stale answer is recognisable. */
+    term: string;
+    /**
+     * How many hits matched **and were visible to this caller**, before the cap.
+     *
+     * After the access filter, deliberately. A total counted before it would let
+     * a caller learn that eleven more types match "payroll" than they can see,
+     * which is the disclosure this route spends most of its code avoiding.
+     */
+    total: number;
+    /** True when {@link total} exceeded the limit and {@link hits} was cut. */
+    truncated: boolean;
+    hits: CatalogSearchHit[];
+}

package/dist/search.types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * What one search across the catalog gives back.
+ *
+ * A separate file from `search.ts` so `client.ts` can re-export these without
+ * dragging the matcher into a browser bundle. The shapes are the contract — a
+ * host writing its own search box needs them as much as it needs the path.
+ *
+ * **Rows, not objects.** Every hit carries what it takes to draw a line and
+ * follow it, and nothing else: no `sql`, no property list, no card layout. That
+ * is not a size optimisation. A search route is the one endpoint whose result
+ * set is chosen by a stranger's typing, so it is the endpoint where "we returned
+ * a bit more than the screen needed" turns into a disclosure nobody reviewed. A
+ * caller that wants the whole saved query asks `GET saved-queries/:id`, which is
+ * a route somebody thought about.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

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