@dudousxd/nestjs-catalog 0.12.0 → 0.14.0

package/dist/catalog.types.d.ts

@@ -15,6 +15,7 @@
  *    need a migration and never need an engineer. That boundary is what makes
  *    it safe to hand the editor to a non-engineer.
  */
+import type { CatalogFilterOperator } from './catalog.filters';
 export type ScalarType = 'string' | 'number' | 'boolean' | 'date' | 'json' | 'uuid' | 'unknown';
 export type RelationKind = '1:1' | '1:m' | 'm:1' | 'm:n';
 /** A single scalar field on an object type. */
@@ -264,6 +265,16 @@ export interface CatalogObjectQuery {
     search?: string;
     sort?: string;
     dir?: 'asc' | 'desc';
+    /**
+     * Column filters, as they arrived: `property:operator:value`, one string each.
+     *
+     * Unvalidated, exactly like `sort` and `search` beside it — these are what a
+     * caller typed. `CatalogService.readObjects` resolves them against the type
+     * before any store sees them, and refuses the read if any of them cannot be
+     * honoured. See `catalog.filters.ts`, which owns both halves of that rule and
+     * is also what a console derives its controls from.
+     */
+    filters?: string[];
 }
 export interface CatalogObjectPage {
     type: string;
@@ -284,6 +295,52 @@ export interface CatalogObjectPage {
         type: ScalarType;
         classification?: string;
         unit?: string;
+        /**
+         * How the source spells this column, when it is not how the property is
+         * named.
+         *
+         * Carried because on a published type the two really do differ: a source
+         * column called `Asset Id` cannot be a SQL identifier, so the property is
+         * `Asset_Id` and `columnName` keeps the original. A reader recognises the
+         * source spelling — it is what is on their spreadsheet — and a filter has to
+         * be built from the property name, so a screen that shows only one of the two
+         * either fails to be recognised or invites a filter on a name that resolves
+         * to nothing. Both are here so a screen can show one and send the other.
+         *
+         * Optional: a page served by a version of this library that predates the
+         * field simply does not say, and a screen falls back to the property name.
+         */
+        columnName?: string;
+        /**
+         * What this column may be filtered with, here and now.
+         *
+         * Derived from the column by `filterOperatorsFor` and then narrowed to what
+         * the mounted store can actually apply, so the list is the server's answer
+         * rather than the screen's guess. **Empty means not filterable** — a
+         * classified column, a blob, or a store that does not filter at all.
+         *
+         * Optional, and absent is not the same as empty: a server older than this
+         * field has not been asked. A screen must read absent the pessimistic way and
+         * offer nothing, because offering a control the server will refuse is worse
+         * than offering none.
+         */
+        filterOperators?: CatalogFilterOperator[];
     }>;
     rows: Array<Record<string, unknown>>;
+    /**
+     * Which load these rows came from, when the store keeps history.
+     *
+     * Reported by the store as part of the read rather than looked up separately,
+     * so it costs nothing and — more importantly — it describes the snapshot that
+     * was actually read rather than the one the caller believes it asked for. A
+     * screen that drew its "you are looking at an old load" banner from its own
+     * state would be trusting the wrong end of the request.
+     *
+     * Absent when the store keeps no snapshots at all.
+     */
+    snapshot?: {
+        id: string;
+        /** False means these rows are NOT what a reader gets by default. */
+        current: boolean;
+    };
 }

package/dist/client.d.ts

@@ -9,11 +9,30 @@
  * own UI. The endpoints alone are not an API; the endpoints plus the response
  * types are.
  */
+import type { DeleteReconciliation, LoadExpectation, RowCountBound, StoredLoadExpectation } from './catalog.pipeline';
 export type { AuditQuery, CatalogAuditEvent, CatalogRevision, Dashboard, DashboardCard, QueryVisualization, SaveQueryInput, SavedQuery, } from './catalog.workspace';
 export { CATALOG_REVISION_LIMIT } 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';
+/**
+ * The filter rule, shipped to the browser deliberately — the same exception, for
+ * the same reason, that `validateWorkflow` further down is.
+ *
+ * A console has to know which control to draw for a column, and the only way for
+ * that answer to match what the server will accept is for both to run this
+ * function. A screen with its own copy of the rules eventually lies: it offers a
+ * control the read refuses, or omits one that would have worked, and on types
+ * that are created at runtime nobody notices until a publisher adds a column. The
+ * functions are pure and import nothing.
+ *
+ * `SnapshotRef` rides along because a snapshot picker is a browser screen and
+ * `GET objects/:name/snapshots` is what fills it. The endpoints alone are not an
+ * API; the endpoints plus the response types are.
+ */
+export { CATALOG_FILTER_LIMIT, CATALOG_FILTER_OPERATORS, coerceFilterValue, encodeObjectFilter, filterOperatorTakesValue, filterOperatorsFor, isCatalogFilterOperator, offeredFilterOperators, parseObjectFilter, resolveObjectFilters, VALUELESS_FILTER_OPERATORS, } from './catalog.filters';
+export type { CatalogFilterableColumn, CatalogFilterOperator, CatalogFilterResolution, CatalogObjectFilter, CatalogResolvedFilter, } from './catalog.filters';
+export type { SnapshotRef } from './catalog.store';
 /** What a tier-0 edit to a type may change. */
 export interface TypePatch {
     displayName?: string;
@@ -38,6 +57,26 @@ export interface ObjectQueryParams {
     search?: string;
     sort?: string;
     dir?: 'asc' | 'desc';
+    /**
+     * `property:operator:value`, one entry per filter, ANDed by the server.
+     *
+     * Named `filter` rather than `filters` because that is the query parameter the
+     * route reads, and this object is handed to a transport that serialises it
+     * verbatim — a name that disagreed with the route would be a filter that is
+     * sent, ignored, and reported by the screen as applied.
+     *
+     * Build entries with `encodeObjectFilter` rather than by hand: it is what the
+     * server parses with, and the two colons are load-bearing.
+     */
+    filter?: string[];
+    /**
+     * Read the type as of an earlier load. Omit for the current one, which is what
+     * every reader must get by default.
+     *
+     * Ids come from `GET objects/:name/snapshots`. A store that keeps no history
+     * refuses this rather than answering with current state.
+     */
+    snapshot?: string;
 }
 /**
  * Builds the paths the catalog controller serves, relative to wherever it was
@@ -106,3 +145,111 @@ export { CONNECTOR_KINDS, isConnectorKind, isTransformLanguage, isWorkflowEdge,
 export { validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_STATUSES, workflowGraphHash, workflowRunOrder, isWorkflowExecutionMode, isWorkflowNodeKind, isWorkflowStatus, } from './catalog.pipeline';
 export type { WorkflowStatus } from './catalog.pipeline';
 export type { CatalogTrace, CatalogTraceList, CatalogTraceOutcome, CatalogTraceSpan, TraceQuery, } from './catalog.workspace';
+export type { CatalogLoadExpectations, DeleteReconciliation, LoadExpectation, RowCountBound, StoredLoadExpectation, } from './catalog.pipeline';
+/**
+ * The three answers to "how do deletions at the source reach this type", as a
+ * value.
+ *
+ * A list rather than only the union, because the editor on the Model screen has
+ * to offer them and a hand-written array in a component is the copy that drifts
+ * — the same argument {@link CONNECTOR_KINDS} makes one screen over. The server
+ * validates against this too: a `strategy` off the wire is `string` until
+ * something checks it, and the check and the dropdown reading one list is what
+ * stops the two from disagreeing about what is acceptable.
+ *
+ * **There are three and there is deliberately no fourth.** Tombstones off a
+ * change feed is the correct answer and needs machinery nothing here has; a
+ * strategy name that nothing implements is a dropdown with a lie in it. See
+ * `DeleteReconciliation` for the whole argument.
+ */
+export declare const DELETE_RECONCILIATION_STRATEGIES: readonly ["accepted", "soft-deleted-at-source", "periodic-full-reload"];
+export type DeleteReconciliationStrategy = (typeof DELETE_RECONCILIATION_STRATEGIES)[number];
+/** Whether a value off the wire names one of the three. */
+export declare function isDeleteReconciliationStrategy(value: unknown): value is DeleteReconciliationStrategy;
+/**
+ * What an operator sends to set a type's expectation.
+ *
+ * Both fields optional and both meaning "leave this alone" when absent, which is
+ * why they are not simply `LoadExpectation`: a request that omits `rowCount`
+ * has said nothing about row counts, and reading that as "clear it" would let a
+ * form that only renders the delete strategy silently drop a bound somebody set.
+ * Clearing the whole stored row is `DELETE`, which is a decision with a verb on
+ * it.
+ */
+export interface LoadExpectationInput {
+    deletes?: DeleteReconciliation;
+    rowCount?: Partial<RowCountBound>;
+}
+/**
+ * The resolved expectation for one type, and which layer won each field.
+ *
+ * The provenance is the whole reason this is not just a `LoadExpectation`. The
+ * policy is sourced from three layers — `host.byType[type]`, then the stored row
+ * an operator set, then `host.default` — and a screen that showed only the
+ * answer would let somebody edit a field this deployment has pinned in code and
+ * watch the edit vanish on the next read, with nothing anywhere saying why.
+ * {@link hostLocked} is what lets it say "this deployment fixed it" instead.
+ */
+export interface ResolvedLoadExpectation {
+    typeName: string;
+    /** The three layers merged, field by field. What the load is actually judged against. */
+    resolved: LoadExpectation;
+    /**
+     * Which layer supplied the delete strategy.
+     *
+     * `'default'` means the host's house-wide `default` did. `'none'` means
+     * nothing did, anywhere — which is not a gap to be filled in silently: it is
+     * the state that refuses every incremental load of this type, and the one the
+     * screen most needs to name.
+     */
+    deletesFrom: 'host' | 'stored' | 'default' | 'none';
+    /**
+     * Which layer supplied the row-count bound — the strongest one that set any
+     * field of it, since the three are merged key by key rather than replaced
+     * whole.
+     *
+     * There is no `'none'`, and that is a statement rather than an omission: a
+     * bound always applies. Where no layer says anything the built-in
+     * `DEFAULT_ROW_COUNT_BOUND` does, and that is what `'default'` covers as well
+     * as the host's own `default`.
+     */
+    rowCountFrom: 'host' | 'stored' | 'default';
+    /** The operator's row, present whether or not it won anything. */
+    stored?: StoredLoadExpectation;
+    /**
+     * Which fields this deployment declared in code, per field.
+     *
+     * True means a stored value for that field would never apply, so the editor
+     * shows it disabled and says so. Only `host.byType[type]` locks: `host.default`
+     * is the weakest layer and an operator's row beats it, so a house-wide default
+     * is not a lock and must not be drawn as one.
+     */
+    hostLocked: {
+        deletes: boolean;
+        rowCount: boolean;
+    };
+}
+/**
+ * Where the per-type expectations sit, relative to wherever the pipeline
+ * controller was mounted.
+ *
+ * A function of the base path rather than a frozen object like
+ * {@link catalogRoutes}, and the difference is the one `routes.ts` in the React
+ * package draws: the catalog controller's paths cannot move, and these move with
+ * whatever `path` the host passed to `CatalogPipelineModule.forRoot` — the
+ * routes below are `<path>/pipeline/expectations`, and `/pipeline` is only the
+ * default.
+ *
+ * Two builders for four routes: `PUT` and `DELETE` address the same path a `GET`
+ * of one type does, and a builder per verb would be three names for one string.
+ */
+export declare function pipelineExpectationRoutes(basePath?: string): {
+    /** Every stored row, plus the types the host has locked. `GET`, `catalog:read`. */
+    readonly expectations: () => string;
+    /**
+     * One type: `GET` for the resolved expectation and its provenance, `PUT` to
+     * set the stored row, `DELETE` to drop it. The writes need `catalog:curate`
+     * and a signed-in person.
+     */
+    readonly expectation: (typeName: string) => string;
+};

package/dist/client.js

@@ -11,12 +11,41 @@
  * types are.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowExecutionMode = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.isWorkflowNode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.catalogRoutes = exports.CATALOG_REVISION_LIMIT = void 0;
+exports.DELETE_RECONCILIATION_STRATEGIES = exports.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowExecutionMode = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.isWorkflowNode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.catalogRoutes = exports.VALUELESS_FILTER_OPERATORS = exports.resolveObjectFilters = exports.parseObjectFilter = exports.offeredFilterOperators = exports.isCatalogFilterOperator = exports.filterOperatorsFor = exports.filterOperatorTakesValue = exports.encodeObjectFilter = exports.coerceFilterValue = exports.CATALOG_FILTER_OPERATORS = exports.CATALOG_FILTER_LIMIT = exports.CATALOG_REVISION_LIMIT = void 0;
+exports.isDeleteReconciliationStrategy = isDeleteReconciliationStrategy;
+exports.pipelineExpectationRoutes = pipelineExpectationRoutes;
 // A value, not a type: a screen saying how far back the history goes should read
 // the number rather than print one of its own. See its docblock for what the cap
 // costs.
 var catalog_workspace_1 = require("./catalog.workspace");
 Object.defineProperty(exports, "CATALOG_REVISION_LIMIT", { enumerable: true, get: function () { return catalog_workspace_1.CATALOG_REVISION_LIMIT; } });
+/**
+ * The filter rule, shipped to the browser deliberately — the same exception, for
+ * the same reason, that `validateWorkflow` further down is.
+ *
+ * A console has to know which control to draw for a column, and the only way for
+ * that answer to match what the server will accept is for both to run this
+ * function. A screen with its own copy of the rules eventually lies: it offers a
+ * control the read refuses, or omits one that would have worked, and on types
+ * that are created at runtime nobody notices until a publisher adds a column. The
+ * functions are pure and import nothing.
+ *
+ * `SnapshotRef` rides along because a snapshot picker is a browser screen and
+ * `GET objects/:name/snapshots` is what fills it. The endpoints alone are not an
+ * API; the endpoints plus the response types are.
+ */
+var catalog_filters_1 = require("./catalog.filters");
+Object.defineProperty(exports, "CATALOG_FILTER_LIMIT", { enumerable: true, get: function () { return catalog_filters_1.CATALOG_FILTER_LIMIT; } });
+Object.defineProperty(exports, "CATALOG_FILTER_OPERATORS", { enumerable: true, get: function () { return catalog_filters_1.CATALOG_FILTER_OPERATORS; } });
+Object.defineProperty(exports, "coerceFilterValue", { enumerable: true, get: function () { return catalog_filters_1.coerceFilterValue; } });
+Object.defineProperty(exports, "encodeObjectFilter", { enumerable: true, get: function () { return catalog_filters_1.encodeObjectFilter; } });
+Object.defineProperty(exports, "filterOperatorTakesValue", { enumerable: true, get: function () { return catalog_filters_1.filterOperatorTakesValue; } });
+Object.defineProperty(exports, "filterOperatorsFor", { enumerable: true, get: function () { return catalog_filters_1.filterOperatorsFor; } });
+Object.defineProperty(exports, "isCatalogFilterOperator", { enumerable: true, get: function () { return catalog_filters_1.isCatalogFilterOperator; } });
+Object.defineProperty(exports, "offeredFilterOperators", { enumerable: true, get: function () { return catalog_filters_1.offeredFilterOperators; } });
+Object.defineProperty(exports, "parseObjectFilter", { enumerable: true, get: function () { return catalog_filters_1.parseObjectFilter; } });
+Object.defineProperty(exports, "resolveObjectFilters", { enumerable: true, get: function () { return catalog_filters_1.resolveObjectFilters; } });
+Object.defineProperty(exports, "VALUELESS_FILTER_OPERATORS", { enumerable: true, get: function () { return catalog_filters_1.VALUELESS_FILTER_OPERATORS; } });
 /**
  * Builds the paths the catalog controller serves, relative to wherever it was
  * mounted. Kept as string builders rather than a fetch wrapper so the host
@@ -113,3 +142,56 @@ Object.defineProperty(exports, "workflowRunOrder", { enumerable: true, get: func
 Object.defineProperty(exports, "isWorkflowExecutionMode", { enumerable: true, get: function () { return catalog_pipeline_2.isWorkflowExecutionMode; } });
 Object.defineProperty(exports, "isWorkflowNodeKind", { enumerable: true, get: function () { return catalog_pipeline_2.isWorkflowNodeKind; } });
 Object.defineProperty(exports, "isWorkflowStatus", { enumerable: true, get: function () { return catalog_pipeline_2.isWorkflowStatus; } });
+/**
+ * The three answers to "how do deletions at the source reach this type", as a
+ * value.
+ *
+ * A list rather than only the union, because the editor on the Model screen has
+ * to offer them and a hand-written array in a component is the copy that drifts
+ * — the same argument {@link CONNECTOR_KINDS} makes one screen over. The server
+ * validates against this too: a `strategy` off the wire is `string` until
+ * something checks it, and the check and the dropdown reading one list is what
+ * stops the two from disagreeing about what is acceptable.
+ *
+ * **There are three and there is deliberately no fourth.** Tombstones off a
+ * change feed is the correct answer and needs machinery nothing here has; a
+ * strategy name that nothing implements is a dropdown with a lie in it. See
+ * `DeleteReconciliation` for the whole argument.
+ */
+exports.DELETE_RECONCILIATION_STRATEGIES = [
+    'accepted',
+    'soft-deleted-at-source',
+    'periodic-full-reload',
+];
+/** Whether a value off the wire names one of the three. */
+function isDeleteReconciliationStrategy(value) {
+    return (typeof value === 'string' &&
+        exports.DELETE_RECONCILIATION_STRATEGIES.includes(value));
+}
+/**
+ * Where the per-type expectations sit, relative to wherever the pipeline
+ * controller was mounted.
+ *
+ * A function of the base path rather than a frozen object like
+ * {@link catalogRoutes}, and the difference is the one `routes.ts` in the React
+ * package draws: the catalog controller's paths cannot move, and these move with
+ * whatever `path` the host passed to `CatalogPipelineModule.forRoot` — the
+ * routes below are `<path>/pipeline/expectations`, and `/pipeline` is only the
+ * default.
+ *
+ * Two builders for four routes: `PUT` and `DELETE` address the same path a `GET`
+ * of one type does, and a builder per verb would be three names for one string.
+ */
+function pipelineExpectationRoutes(basePath = '/pipeline') {
+    const base = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+    return {
+        /** Every stored row, plus the types the host has locked. `GET`, `catalog:read`. */
+        expectations: () => `${base}/expectations`,
+        /**
+         * One type: `GET` for the resolved expectation and its provenance, `PUT` to
+         * set the stored row, `DELETE` to drop it. The writes need `catalog:curate`
+         * and a signed-in person.
+         */
+        expectation: (typeName) => `${base}/expectations/${encodeURIComponent(typeName)}`,
+    };
+}

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { type CatalogOverlayStore, FileCatalogOverlayStore, InMemoryCatalogOverl
 export { CATALOG_OVERLAY_STORE } from './catalog.overlay-store.token';
 export { MikroOrmCatalogRegistry } from './catalog.registry';
 export { CatalogRegistry } from './catalog.registry.base';
-export { CATALOG_PIPELINE_STORE, type CatalogConnection, type CatalogConnector, type ConnectionCheck, CONNECTOR_KINDS, type CatalogPipelineStore, type CatalogStageStore, type CatalogTransform, type CatalogWorkflow, type CatalogWorkflowCapabilities, type CatalogWorkflowStore, type ConnectorKind, type ConnectorRun, isConnectorKind, isPipelineStore, isTransformLanguage, supportsTransformRevisions, isWorkflowEdge, isWorkflowExecutionMode, isWorkflowNode, isWorkflowNodeKind, isWorkflowStatus, supportsWorkflows, supportsWorkflowStages, TRANSFORM_RUNNER, TRANSFORM_LANGUAGES, type TransformLanguage, type TransformResult, type TransformRunner, validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_STATUSES, type WorkflowEdge, type WorkflowExecutionMode, type WorkflowGraph, workflowGraphHash, type WorkflowIssueCode, type WorkflowNode, type WorkflowNodeKind, type WorkflowNodeOutcome, type WorkflowNodeStepInput, type WorkflowNodeStepOutput, workflowRunOrder, type WorkflowSinkNode, type WorkflowSourceNode, type WorkflowStageRef, type WorkflowStatus, type WorkflowTransformNode, type WorkflowValidationIssue, } from './catalog.pipeline';
+export { CATALOG_PIPELINE_STORE, type CatalogConnection, type CatalogConnector, type ConnectionCheck, CONNECTOR_KINDS, type CatalogLoadExpectations, type CatalogLoadExpectationStore, type CatalogPipelineStore, type CatalogStageStore, type CatalogTransform, type CatalogWorkflow, type CatalogWorkflowCapabilities, type CatalogWorkflowStore, type ConnectorKind, type ConnectorRun, type DeleteReconciliation, isConnectorKind, isPipelineStore, isTransformLanguage, type LoadExpectation, type RowCountBound, type StoredLoadExpectation, supportsLoadExpectations, supportsTransformRevisions, isWorkflowEdge, isWorkflowExecutionMode, isWorkflowNode, isWorkflowNodeKind, isWorkflowStatus, supportsWorkflows, supportsWorkflowStages, TRANSFORM_RUNNER, TRANSFORM_LANGUAGES, type TransformLanguage, type TransformResult, type TransformRunner, validateWorkflow, WORKFLOW_EXECUTION_MODES, WORKFLOW_ISSUE_CODES, WORKFLOW_NODE_ID_PATTERN, WORKFLOW_NODE_KINDS, WORKFLOW_STATUSES, type WorkflowEdge, type WorkflowExecutionMode, type WorkflowGraph, workflowGraphHash, type WorkflowIssueCode, type WorkflowNode, type WorkflowNodeKind, type WorkflowNodeOutcome, type WorkflowNodeStepInput, type WorkflowNodeStepOutput, workflowRunOrder, type WorkflowSinkNode, type WorkflowSourceNode, type WorkflowStageRef, type WorkflowStatus, type WorkflowTransformNode, type WorkflowValidationIssue, } from './catalog.pipeline';
 export * from './catalog.environment';
 export { QueryCache, toCsv } from './catalog.query-cache';
 export { SubprocessTransformRunner, type TransformRunnerOptions, } from './transform-runner';
@@ -18,7 +18,8 @@ export type { CatalogSearchField, CatalogSearchHit, CatalogSearchKind, CatalogSe
 export { type AuditQuery, CATALOG_REVISION_LIMIT, CATALOG_TRACE_OUTCOMES, CATALOG_TRACE_STORE, CATALOG_WORKSPACE_STORE, type CatalogAuditEvent, type CatalogRevision, 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, supportsSavedQueryRevisions, 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';
-export { assertNoColumnCollisions, CATALOG_RESERVED_COLUMNS, CATALOG_SNAPSHOT_MODES, CATALOG_STORE, type CarryForwardResult, type CatalogColumnCollision, CatalogColumnCollisionError, type CatalogMergeStore, type CatalogReadQuery, type CatalogReadResult, type CatalogReadStore, type CatalogReservedColumn, type CatalogSnapshotMode, type CatalogStoreCapabilities, type CatalogWriteStore, type ColumnCollisionOptions, findColumnCollisions, isCatalogStoreCapabilities, isReservedColumn, isWriteStore, type SnapshotRef, supportsCarryForward, } from './catalog.store';
+export * from './catalog.filters';
+export { assertNoColumnCollisions, assertSafeIdentifier, CATALOG_RESERVED_COLUMNS, CATALOG_SNAPSHOT_MODES, CATALOG_STORE, type CarryForwardResult, type CatalogColumnCollision, CatalogColumnCollisionError, type CatalogFilteringReadStore, supportsObjectFilters, type CatalogMergeStore, type CatalogReadQuery, type CatalogReadResult, type CatalogReadStore, type CatalogReservedColumn, type CatalogSnapshotMode, type CatalogStoreCapabilities, type CatalogWriteStore, type ColumnCollisionOptions, findColumnCollisions, isCatalogStoreCapabilities, isReservedColumn, isSafeIdentifier, isWriteStore, type SnapshotRef, supportsCarryForward, UnsafeIdentifierError, } from './catalog.store';
 export { MikroOrmReadStore } from './stores/mikro-orm-read.store';
 export type { CatalogGraph, CatalogObjectPage, CatalogObjectQuery, CatalogObjectTypeDef, CatalogOverlay, CatalogPropertyDef, CatalogRelationDef, CatalogSnapshot, RelationKind, ScalarType, } from './catalog.types';
 export { REQUIRED_SCOPES, REQUIRES_HUMAN, RequireHuman, RequireScopes, } from './catalog.route-auth';

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.bestMatch = exports.MAX_SEARCH_LIMIT = exports.DEFAULT_SEARCH_LIMIT = exports.CatalogService = exports.SubprocessTransformRunner = exports.toCsv = exports.QueryCache = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = 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.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowNode = exports.isWorkflowExecutionMode = exports.isWorkflowEdge = exports.supportsTransformRevisions = 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.curationActor = exports.channelNameFor = exports.catalogEventPhase = exports.UNATTRIBUTED_PRINCIPAL_ID = 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.supportsSavedQueryRevisions = exports.isWorkspaceStore = exports.isTraceStore = exports.isCatalogTraceOutcome = exports.embeddedVisualization = exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = exports.CATALOG_REVISION_LIMIT = exports.visibleToPrincipal = exports.searchCatalog = exports.maySearch = exports.emptySearch = void 0;
+exports.MAX_SEARCH_LIMIT = exports.DEFAULT_SEARCH_LIMIT = exports.CatalogService = exports.SubprocessTransformRunner = exports.toCsv = exports.QueryCache = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_STATUSES = 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.isWorkflowStatus = exports.isWorkflowNodeKind = exports.isWorkflowNode = exports.isWorkflowExecutionMode = exports.isWorkflowEdge = exports.supportsTransformRevisions = exports.supportsLoadExpectations = 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.curationActor = exports.channelNameFor = exports.catalogEventPhase = exports.UNATTRIBUTED_PRINCIPAL_ID = 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.UnsafeIdentifierError = exports.supportsCarryForward = exports.isWriteStore = exports.isSafeIdentifier = exports.isReservedColumn = exports.isCatalogStoreCapabilities = exports.findColumnCollisions = exports.supportsObjectFilters = exports.CatalogColumnCollisionError = exports.CATALOG_STORE = exports.CATALOG_SNAPSHOT_MODES = exports.CATALOG_RESERVED_COLUMNS = exports.assertSafeIdentifier = 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.supportsSavedQueryRevisions = exports.isWorkspaceStore = exports.isTraceStore = exports.isCatalogTraceOutcome = exports.embeddedVisualization = exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = exports.CATALOG_REVISION_LIMIT = exports.visibleToPrincipal = exports.searchCatalog = exports.maySearch = exports.emptySearch = exports.bestMatch = 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; } });
@@ -59,6 +59,7 @@ Object.defineProperty(exports, "CONNECTOR_KINDS", { enumerable: true, get: funct
 Object.defineProperty(exports, "isConnectorKind", { enumerable: true, get: function () { return catalog_pipeline_1.isConnectorKind; } });
 Object.defineProperty(exports, "isPipelineStore", { enumerable: true, get: function () { return catalog_pipeline_1.isPipelineStore; } });
 Object.defineProperty(exports, "isTransformLanguage", { enumerable: true, get: function () { return catalog_pipeline_1.isTransformLanguage; } });
+Object.defineProperty(exports, "supportsLoadExpectations", { enumerable: true, get: function () { return catalog_pipeline_1.supportsLoadExpectations; } });
 Object.defineProperty(exports, "supportsTransformRevisions", { enumerable: true, get: function () { return catalog_pipeline_1.supportsTransformRevisions; } });
 Object.defineProperty(exports, "isWorkflowEdge", { enumerable: true, get: function () { return catalog_pipeline_1.isWorkflowEdge; } });
 Object.defineProperty(exports, "isWorkflowExecutionMode", { enumerable: true, get: function () { return catalog_pipeline_1.isWorkflowExecutionMode; } });
@@ -131,17 +132,28 @@ Object.defineProperty(exports, "StaticKeyPrincipalResolver", { enumerable: true,
 // implemented only by a host willing to restate them — which nothing in this
 // repo would have caught: no consumer compiles against the built barrel here.
 __exportStar(require("./catalog.access"), exports);
+// The filter rule, whole. A store implementing `CatalogFilteringReadStore` needs
+// the operator list to declare what it applies and `CatalogResolvedFilter` to
+// read what it was handed, and a host writing its own objects route needs
+// `resolveObjectFilters` — shipping the interface without them would be the same
+// unimplementable seam the barrel spec above was written after. It is also on
+// `/client`, because the console derives its controls from the same function.
+__exportStar(require("./catalog.filters"), exports);
 var catalog_store_1 = require("./catalog.store");
 Object.defineProperty(exports, "assertNoColumnCollisions", { enumerable: true, get: function () { return catalog_store_1.assertNoColumnCollisions; } });
+Object.defineProperty(exports, "assertSafeIdentifier", { enumerable: true, get: function () { return catalog_store_1.assertSafeIdentifier; } });
 Object.defineProperty(exports, "CATALOG_RESERVED_COLUMNS", { enumerable: true, get: function () { return catalog_store_1.CATALOG_RESERVED_COLUMNS; } });
 Object.defineProperty(exports, "CATALOG_SNAPSHOT_MODES", { enumerable: true, get: function () { return catalog_store_1.CATALOG_SNAPSHOT_MODES; } });
 Object.defineProperty(exports, "CATALOG_STORE", { enumerable: true, get: function () { return catalog_store_1.CATALOG_STORE; } });
 Object.defineProperty(exports, "CatalogColumnCollisionError", { enumerable: true, get: function () { return catalog_store_1.CatalogColumnCollisionError; } });
+Object.defineProperty(exports, "supportsObjectFilters", { enumerable: true, get: function () { return catalog_store_1.supportsObjectFilters; } });
 Object.defineProperty(exports, "findColumnCollisions", { enumerable: true, get: function () { return catalog_store_1.findColumnCollisions; } });
 Object.defineProperty(exports, "isCatalogStoreCapabilities", { enumerable: true, get: function () { return catalog_store_1.isCatalogStoreCapabilities; } });
 Object.defineProperty(exports, "isReservedColumn", { enumerable: true, get: function () { return catalog_store_1.isReservedColumn; } });
+Object.defineProperty(exports, "isSafeIdentifier", { enumerable: true, get: function () { return catalog_store_1.isSafeIdentifier; } });
 Object.defineProperty(exports, "isWriteStore", { enumerable: true, get: function () { return catalog_store_1.isWriteStore; } });
 Object.defineProperty(exports, "supportsCarryForward", { enumerable: true, get: function () { return catalog_store_1.supportsCarryForward; } });
+Object.defineProperty(exports, "UnsafeIdentifierError", { enumerable: true, get: function () { return catalog_store_1.UnsafeIdentifierError; } });
 var mikro_orm_read_store_1 = require("./stores/mikro-orm-read.store");
 Object.defineProperty(exports, "MikroOrmReadStore", { enumerable: true, get: function () { return mikro_orm_read_store_1.MikroOrmReadStore; } });
 var catalog_route_auth_1 = require("./catalog.route-auth");

package/dist/stores/mikro-orm-read.store.d.ts

@@ -1,6 +1,6 @@
 import { EntityManager } from '@mikro-orm/core';
 import { MikroOrmCatalogRegistry } from '../catalog.registry';
-import type { CatalogReadQuery, CatalogReadResult, CatalogReadStore, CatalogStoreCapabilities } from '../catalog.store';
+import type { CatalogFilteringReadStore, CatalogReadQuery, CatalogReadResult, CatalogStoreCapabilities } from '../catalog.store';
 import type { CatalogObjectTypeDef } from '../catalog.types';
 /**
  * Reads objects straight out of the application's own tables, through the ORM
@@ -11,10 +11,16 @@ import type { CatalogObjectTypeDef } from '../catalog.types';
  * trade is that there is also no history — the tables hold current state, and
  * nothing here can show you last Tuesday.
  */
-export declare class MikroOrmReadStore implements CatalogReadStore {
+export declare class MikroOrmReadStore implements CatalogFilteringReadStore {
     private readonly registry;
     private readonly em;
     readonly capabilities: CatalogStoreCapabilities;
+    /**
+     * All of them: every operator maps onto a MikroORM query-builder operator, and
+     * the ORM writes the column name from the entity metadata rather than from
+     * anything a caller sent.
+     */
+    readonly objectFilterOperators: readonly ["eq", "ne", "contains", "gte", "lte", "gt", "lt", "empty", "notEmpty"];
     constructor(registry: MikroOrmCatalogRegistry, em: EntityManager);
     read(type: CatalogObjectTypeDef, fields: string[], query: CatalogReadQuery): Promise<CatalogReadResult>;
 }

package/dist/stores/mikro-orm-read.store.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MikroOrmReadStore = void 0;
 const core_1 = require("@mikro-orm/core");
 const common_1 = require("@nestjs/common");
+const catalog_filters_1 = require("../catalog.filters");
 const catalog_registry_1 = require("../catalog.registry");
 /**
  * Reads objects straight out of the application's own tables, through the ORM
@@ -30,6 +31,12 @@ let MikroOrmReadStore = class MikroOrmReadStore {
         writable: false,
         timeTravel: false,
     };
+    /**
+     * All of them: every operator maps onto a MikroORM query-builder operator, and
+     * the ORM writes the column name from the entity metadata rather than from
+     * anything a caller sent.
+     */
+    objectFilterOperators = catalog_filters_1.CATALOG_FILTER_OPERATORS;
     constructor(registry, em) {
         this.registry = registry;
         this.em = em;
@@ -48,7 +55,7 @@ let MikroOrmReadStore = class MikroOrmReadStore {
         // No explicit type arguments: `findAndCount` declares `Fields extends string
         // = never`, so naming even one generic makes the rest fall back to their
         // defaults and types `fields` as `never[]`. Inference gets it right.
-        const [rows, total] = await em.findAndCount(entityClass, buildWhere(type, query.search), {
+        const [rows, total] = await em.findAndCount(entityClass, buildWhere(type, query), {
             limit: size,
             offset: (page - 1) * size,
             orderBy: buildOrderBy(type, query.sort, query.dir),
@@ -67,19 +74,78 @@ exports.MikroOrmReadStore = MikroOrmReadStore = __decorate([
         core_1.EntityManager])
 ], MikroOrmReadStore);
 /**
- * Only string columns the catalog says are visible.
+ * The search term and the column filters, ANDed.
  *
- * A search that reached a classified column would leak it through row
- * membership even though the value is never rendered.
+ * Search reaches only string columns the catalog says are visible: a search that
+ * reached a classified column would leak it through row membership even though
+ * the value is never rendered. `filterOperatorsFor` refuses a classified column
+ * for the same reason and a sharper one — a range filter lets a reader
+ * binary-search a value they may not see.
+ *
+ * The filters are ANDed with each other and with the search, which is what makes
+ * a filter narrowing: two conditions on one column express a range, and a caller
+ * that wanted alternatives has `contains` or a second request.
  */
-function buildWhere(type, search) {
-    const term = search?.trim();
-    if (!term)
-        return {};
-    const searchable = type.properties.filter((p) => !p.hidden && p.type === 'string' && !p.classification);
-    if (searchable.length === 0)
+function buildWhere(type, query) {
+    const conditions = [];
+    const term = query.search?.trim();
+    if (term) {
+        const searchable = type.properties.filter((p) => !p.hidden && p.type === 'string' && !p.classification);
+        if (searchable.length > 0) {
+            conditions.push({ $or: searchable.map((p) => ({ [p.name]: { $like: `%${term}%` } })) });
+        }
+    }
+    for (const filter of query.filters ?? []) {
+        conditions.push({ [filter.property.name]: comparison(filter) });
+    }
+    if (conditions.length === 0)
         return {};
-    return { $or: searchable.map((p) => ({ [p.name]: { $like: `%${term}%` } })) };
+    if (conditions.length === 1)
+        return conditions[0];
+    return { $and: conditions };
+}
+/**
+ * One operator as MikroORM spells it.
+ *
+ * The property name is the ORM's own — it came off the type, which was built
+ * from the entity metadata — so the column in the emitted SQL is written by the
+ * ORM from that metadata and never by string concatenation here. That is the same
+ * guarantee the sort above relies on.
+ */
+function comparison(filter) {
+    const value = filter.value;
+    switch (filter.op) {
+        case 'eq':
+            return { $eq: value };
+        case 'ne':
+            // `!=` in SQL is never true of NULL, so a row whose column is empty would
+            // drop out of "is not X" — which reads as those rows having the value.
+            return { $or: [{ $ne: value }, { $eq: null }] };
+        case 'contains':
+            return { $like: `%${String(value)}%` };
+        case 'gt':
+            return { $gt: value };
+        case 'gte':
+            return { $gte: value };
+        case 'lt':
+            return { $lt: value };
+        case 'lte':
+            return { $lte: value };
+        case 'empty':
+            // A blank string is empty to a reader, and only a text column can hold
+            // one. Both spellings, so "no value" means what it says on either.
+            return { $or: [{ $eq: null }, { $eq: '' }] };
+        case 'notEmpty':
+            return { $and: [{ $ne: null }, { $ne: '' }] };
+        default:
+            // No operator falls through to a silent `{}`, which would be a filter
+            // that matches everything. An operator added to the contract and not to
+            // this switch fails to compile here rather than at read time.
+            return unknownOperator(filter.op);
+    }
+}
+function unknownOperator(operator) {
+    throw new common_1.BadRequestException(`This store cannot filter with ${String(operator)}.`);
 }
 /** Only ever a column the catalog vouched for; falls back to the key. */
 function buildOrderBy(type, sort, dir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-catalog",
-  "version": "0.12.0",
+  "version": "0.14.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",