npm - @dudousxd/nestjs-catalog - Versions diffs - 0.6.0 → 0.8.0 - Mend

@dudousxd/nestjs-catalog 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/dist/catalog.controller.d.ts +6 -0
package/dist/catalog.controller.js +54 -0
package/dist/catalog.decorators.d.ts +17 -0
package/dist/catalog.decorators.js +17 -0
package/dist/catalog.environment.d.ts +39 -0
package/dist/catalog.environment.js +50 -0
package/dist/catalog.pipeline.d.ts +19 -0
package/dist/catalog.registry.base.d.ts +46 -1
package/dist/catalog.registry.base.js +102 -0
package/dist/catalog.registry.d.ts +1 -2
package/dist/catalog.registry.js +53 -39
package/dist/catalog.service.d.ts +17 -0
package/dist/catalog.service.js +72 -0
package/dist/catalog.types.d.ts +107 -2
package/dist/client.d.ts +11 -0
package/dist/client.js +10 -0
package/dist/index.d.ts +2 -0
package/dist/index.js +17 -2
package/dist/search.d.ts +184 -0
package/dist/search.js +345 -0
package/dist/search.types.d.ts +93 -0
package/dist/search.types.js +17 -0
package/package.json +1 -1

package/dist/catalog.service.js CHANGED Viewed

@@ -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/catalog.types.d.ts CHANGED Viewed

@@ -54,7 +54,24 @@ export interface CatalogPropertyDef {
     /** True when the value came from a hand-written decorator rather than the ORM. */
     enriched: boolean;
 }
-/** A link between two object types. Derived entirely from the ORM. */
+/**
+ * A link between two object types — the thing that makes this an ontology
+ * rather than a list of tables.
+ *
+ * **Structure derived, semantics declared**, the same split as everywhere else.
+ * A `@ManyToOne` already names its target, its kind and its join column, so none
+ * of that is ever written by hand — a decorator that could restate it is a
+ * decorator that can disagree with the schema. What a human adds is what they
+ * add to a scalar, a label and a meaning, through `@CatalogProperty` or the
+ * overlay; both key on the property name and so reach a relation without having
+ * to know it is one.
+ *
+ * **One row per declaration, not per link.** `@ManyToOne(() => Base)` on `Mvr`
+ * with the matching `@OneToMany` on `Base` is two rows describing one link.
+ * Collapsing them here would mean `Base` could not carry its own label for the
+ * end it declares, and a type could not say what it points at without consulting
+ * every other type. The graph collapses them instead — see {@link CatalogGraph}.
+ */
 export interface CatalogRelationDef {
     name: string;
     displayName: string;
@@ -67,6 +84,39 @@ export interface CatalogRelationDef {
     nullable: boolean;
     hidden: boolean;
     order: number;
+    /**
+     * True when this side physically holds the key.
+     *
+     * The two ends of a link are not interchangeable. The owning end is where the
+     * foreign key actually is, so it is the end a join is written from, the end
+     * whose column can be indexed, and the end whose removal breaks the link. A
+     * `1:m` is never the owner — the key lives on the many side.
+     */
+    owner: boolean;
+    /**
+     * The property on {@link targetType} that is the other end of this same link,
+     * when the ORM knows it (MikroORM's `mappedBy` / `inversedBy`).
+     *
+     * This is what lets two rows be recognised as one link. Pairing them by name
+     * instead only works for the accident of both ends being spelled the same:
+     * `Mvr.base` and `Base.mvrs` are one link and would otherwise draw two edges,
+     * which is exactly the picture a graph is supposed to prevent.
+     */
+    inverseName?: string;
+    /**
+     * Whether {@link targetType} is a type this catalog actually holds.
+     *
+     * False when the target was excluded by configuration, or belongs to an
+     * application that has not published it. The relation is still reported: that
+     * an MVR points at something called `Base` is true, and when the other end is
+     * missing that is the most useful single fact about it. Dropping it silently
+     * would leave a type looking unlinked when it is really linked to something
+     * out of reach — but drawing it as a navigable edge promises a node that
+     * cannot be opened, so the graph omits it and the type page keeps it, marked.
+     */
+    targetPublished: boolean;
+    /** True when a human has labelled or described this link. */
+    enriched: boolean;
 }
 /** One node of the ontology. */
 export interface CatalogObjectTypeDef {
@@ -97,6 +147,40 @@ export interface CatalogObjectTypeDef {
      * came from a regex and are probably wrong.
      */
     enriched: boolean;
+    /**
+     * When readers started seeing the data this type currently serves.
+     *
+     * `committedAt` of the newest committed snapshot, not `createdAt`: a load that
+     * was written and never committed is not what anybody is reading, and dating
+     * the type by it would report freshness nobody has.
+     *
+     * **Absent means no committed snapshot ever**, which is a different statement
+     * from "committed a year ago" — a type published by a schema and never loaded
+     * looked exactly like a type loaded daily until this field existed, and both
+     * looked exactly like a type whose publisher was deleted six months ago.
+     *
+     * Carried on the type rather than fetched per type on demand. The value of
+     * this signal is that it arrives without anybody going to look for it, and a
+     * field costing one request per row on a screen listing every type is a field
+     * that screen will not use.
+     */
+    lastCommittedAt?: string;
+    /**
+     * Rows in that snapshot.
+     *
+     * Here for a failure the timestamp cannot show: a connector that starts
+     * returning 12 rows where it returned 40,000 produces data that is wrong and
+     * *fresh*, so every staleness signal reports it as healthy. The count next to
+     * the date is what makes that visible, and it is the same read.
+     */
+    rowCount?: number;
+    /**
+     * Which application committed it.
+     *
+     * Because "stale since March" is never the last question — "so who was
+     * loading this?" is — and the answer is already in the row being read.
+     */
+    lastPrincipalId?: string;
     properties: CatalogPropertyDef[];
     relations: CatalogRelationDef[];
 }
@@ -108,12 +192,27 @@ export interface CatalogSnapshot {
     stats: {
         types: number;
         properties: number;
+        /**
+         * Declared relations, summed over the types — **not** distinct links. A link
+         * declared at both ends counts twice, because that is what this number is
+         * derived from and quietly halving it would make it disagree with the rows
+         * on the type pages that produce it. `getGraph().edges.length` is the count
+         * of links.
+         */
         relations: number;
         enrichedTypes: number;
     };
     types: CatalogObjectTypeDef[];
 }
-/** Nodes and edges, for drawing the ontology. */
+/**
+ * Nodes and edges, for drawing the ontology.
+ *
+ * One edge per **link**, not per declaration: a link declared at both ends is
+ * one line on the picture, drawn from the end that holds the key so the arrow
+ * points the way a join is written. And every edge lands on a node that is
+ * present — a target this catalog does not hold produces no edge, because an
+ * edge to nowhere is a node the reader will try to click.
+ */
 export interface CatalogGraph {
     nodes: Array<{
         id: string;
@@ -143,6 +242,12 @@ export interface CatalogOverlay {
         icon?: string;
         group?: string;
         titleProperty?: string;
+        /**
+         * Keyed by property name — and a relation is a property to whoever is
+         * looking, so a link's label and description are curated through this map
+         * too, under the relation's own name. That is why curating a link needs no
+         * new route and no new patch shape: `patchProperty` already accepts one.
+         */
         properties?: Record<string, {
             displayName?: string;
             description?: string;

package/dist/client.d.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 {};