@dudousxd/nestjs-catalog 0.13.0 → 0.14.0

package/dist/catalog.controller.js

@@ -191,7 +191,7 @@ function createCatalogController(path, guards, decorators = []) {
             return this.registry.getSnapshot();
         }
         /** One generic read endpoint for every type in the catalog. */
-        objects(name, page, size, search, sort, dir, snapshot) {
+        objects(name, page, size, search, sort, dir, snapshot, filter) {
             return this.service.readObjects(name, {
                 page: page ? Number(page) : undefined,
                 size: size ? Number(size) : undefined,
@@ -199,6 +199,7 @@ function createCatalogController(path, guards, decorators = []) {
                 sort,
                 dir: dir === 'desc' ? 'desc' : 'asc',
                 snapshot,
+                filters: repeatable(filter),
             });
         }
         /**
@@ -492,8 +493,9 @@ function createCatalogController(path, guards, decorators = []) {
         __param(4, (0, common_1.Query)('sort')),
         __param(5, (0, common_1.Query)('dir')),
         __param(6, (0, common_1.Query)('snapshot')),
+        __param(7, (0, common_1.Query)('filter')),
         __metadata("design:type", Function),
-        __metadata("design:paramtypes", [String, String, String, String, String, String, String]),
+        __metadata("design:paramtypes", [String, String, String, String, String, String, String, Object]),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "objects", null);
     __decorate([
@@ -739,6 +741,20 @@ function actorOf(request, claimed) {
         return resolved;
     return claimed?.trim() || 'console';
 }
+/**
+ * A query parameter that may appear once or many times, as a list either way.
+ *
+ * Unlike {@link parseOutcomes} below, nothing is split on commas and nothing is
+ * dropped. A filter's value is free text that may contain a comma — a
+ * description, a date range written by hand — and an unrecognised filter must
+ * reach the service so it can be refused by name rather than vanish into an
+ * unfiltered page.
+ */
+function repeatable(raw) {
+    if (raw === undefined)
+        return undefined;
+    return Array.isArray(raw) ? raw : [raw];
+}
 /**
  * `?outcome=failed`, `?outcome=failed,incomplete`, `?outcome=a&outcome=b`.
  *

package/dist/catalog.filters.d.ts

@@ -0,0 +1,170 @@
+import type { CatalogPropertyDef, ScalarType } from './catalog.types';
+/**
+ * Filtering a catalogued type, derived from the type.
+ *
+ * **Nothing here lists a filterable column, and nothing anywhere else may.** The
+ * types this catalog serves are created at runtime — `PUT publish/:type/schema`
+ * writes the properties and the store builds the physical columns from them — so
+ * a hand-maintained list of what is filterable is a list that goes quiet the day
+ * somebody publishes a column nobody edited it for. That is the failure mode this
+ * module exists to remove: the operators a column offers are a function of the
+ * column, computed by {@link filterOperatorsFor}, and both the server (deciding
+ * what it will accept) and the console (deciding what to draw) call that one
+ * function. A screen offering a control the server would refuse, or refusing one
+ * the server would take, is then not expressible.
+ *
+ * This is also why `@dudousxd/nestjs-filter` is not what is used here. That
+ * library derives its filters from entities and routes known at compile time, and
+ * these types do not exist at compile time.
+ *
+ * **The module is pure and imports nothing but types**, because it ships to the
+ * browser through `@dudousxd/nestjs-catalog/client` — the same reason
+ * `validateWorkflow` does. A second copy of the derivation living in the console
+ * is exactly the drift that entry point exists to prevent.
+ */
+/**
+ * Every operator, in the order a control should offer them.
+ *
+ * One list, so nothing narrows a stored or transmitted operator against a second
+ * hand-maintained copy of these names — the same argument
+ * `CATALOG_SNAPSHOT_MODES` makes one file over.
+ *
+ * There is no `between`. A range is `gte` and `lte` on one property, which is two
+ * filters that compose with everything else rather than one operator that needs
+ * its own wire form, its own second value and its own "what if the ends are the
+ * wrong way round" answer.
+ */
+export declare const CATALOG_FILTER_OPERATORS: readonly ["eq", "ne", "contains", "gte", "lte", "gt", "lt", "empty", "notEmpty"];
+export type CatalogFilterOperator = (typeof CATALOG_FILTER_OPERATORS)[number];
+export declare function isCatalogFilterOperator(value: string): value is CatalogFilterOperator;
+/**
+ * The operators that take no value.
+ *
+ * "Has no value" cannot be spelled as a comparison — `= NULL` matches nothing in
+ * SQL and `= ''` misses the NULLs — so it is an operator rather than a value a
+ * caller types, and a filter carrying one is complete without a `value`.
+ */
+export declare const VALUELESS_FILTER_OPERATORS: readonly ["empty", "notEmpty"];
+export declare function filterOperatorTakesValue(operator: CatalogFilterOperator): boolean;
+/** One filter as it crosses the wire: a property name, an operator, raw text. */
+export interface CatalogObjectFilter {
+    /**
+     * The property's `name`, which is its identity in the type — never its
+     * `columnName`. On a published type the two differ whenever the source spelled
+     * a column in a way SQL cannot: `Asset Id` arrives as `columnName` and the
+     * property is `Asset_Id`. Filtering by the source spelling would resolve to no
+     * property at all on every one of them.
+     */
+    property: string;
+    op: CatalogFilterOperator;
+    /** Absent for {@link VALUELESS_FILTER_OPERATORS}. Text, as it was typed. */
+    value?: string;
+}
+/**
+ * The minimum a column has to say for the rule below to run on it.
+ *
+ * Structural rather than `CatalogPropertyDef`, because the console holds the
+ * *page's* columns rather than the type's — `CatalogObjectPage.columns` — and the
+ * whole point is that both sides ask the same function. Both shapes satisfy this.
+ */
+export interface CatalogFilterableColumn {
+    name: string;
+    type: ScalarType;
+    hidden?: boolean;
+    classification?: string;
+}
+/**
+ * What may be filtered on this column, derived from what the column is.
+ *
+ * An empty list means "not filterable", and there are three ways to get one.
+ *
+ * **Hidden** is the overlay saying a column is not part of the generic UI, and a
+ * filter is generic UI.
+ *
+ * **Classified** is the one worth stating out loud, because the column is
+ * otherwise perfectly filterable and the value is never rendered anyway. It is
+ * excluded for the reason `MikroOrmReadStore.buildWhere` already excludes it from
+ * SEARCH: a predicate over a classified column leaks it through row membership.
+ * Filtering is strictly worse than searching there — `gte`/`lte` let a reader
+ * binary-search a value they may not see, in as many requests as it takes.
+ *
+ * **`json`** because a blob has no useful comparison, and it is already dropped
+ * from the readable columns by `CatalogService.visibleColumns`.
+ */
+export declare function filterOperatorsFor(column: CatalogFilterableColumn): CatalogFilterOperator[];
+/** Which operators a column offers, once the store's own limits are applied. */
+export declare function offeredFilterOperators(column: CatalogFilterableColumn, supported: readonly CatalogFilterOperator[]): CatalogFilterOperator[];
+/**
+ * `property:op:value`, repeated once per filter.
+ *
+ * The value is everything after the second colon, so it may contain colons — a
+ * timestamp does. A property name containing one cannot be addressed by this
+ * form; that is refused by name in {@link resolveObjectFilters} rather than
+ * silently mis-parsed, because a filter that quietly does not apply is a screen
+ * showing every row as though it had been filtered.
+ */
+export declare function encodeObjectFilter(filter: CatalogObjectFilter): string;
+export declare function parseObjectFilter(raw: string): CatalogObjectFilter | undefined;
+/**
+ * A filter with the property it names already resolved to the type's own.
+ *
+ * The property is carried as the definition rather than as a string, and that is
+ * the guard rather than a nicety: a store builds a predicate out of a column
+ * name, and the only names it can be handed here are ones that came off the type.
+ * A caller's string never reaches SQL — it is matched against the type first, and
+ * the store then maps the property to its physical column exactly as `sort` and
+ * `search` already do, through the adapter's identifier rule.
+ */
+export interface CatalogResolvedFilter {
+    property: CatalogPropertyDef;
+    op: CatalogFilterOperator;
+    /** Coerced to the property's type. Absent for the valueless operators. */
+    value?: string | number | boolean | Date;
+}
+export interface CatalogFilterResolution {
+    filters: CatalogResolvedFilter[];
+    /** One sentence per filter that could not be honoured. Empty means all were. */
+    problems: string[];
+}
+/**
+ * How many filters one read may carry.
+ *
+ * A cap rather than none, because every filter is another conjunct in the two
+ * statements a paged read issues, and a caller that can send five hundred can
+ * make one request cost whatever it likes. Twenty is far past what a person
+ * builds by hand and far short of anything that would trouble the optimiser.
+ */
+export declare const CATALOG_FILTER_LIMIT = 20;
+/**
+ * Turn what arrived into what a store may be given, or say why not.
+ *
+ * **Unhonourable filters are reported, never dropped.** The neighbouring
+ * `parseOutcomes` on the controller drops an unrecognised trace outcome on
+ * purpose, and this goes the other way for a reason that is worth the two
+ * sentences: dropping there costs a filter, so a typo widens the result set and
+ * shows more traces than asked for. Dropping HERE would narrow nothing — the read
+ * would come back unfiltered and the screen would present the whole table as
+ * though it were the matching rows. A filter that silently does not apply is the
+ * one failure mode a filtering UI must not have.
+ *
+ * @param columns the properties this reader may see. Deliberately the visible,
+ * non-blob columns rather than `type.properties`: a filter is only ever resolved
+ * against what the same request would return.
+ */
+export declare function resolveObjectFilters(columns: readonly CatalogPropertyDef[], raw: readonly string[]): CatalogFilterResolution;
+/**
+ * A typed value, or the reason there is none.
+ *
+ * Refusing rather than passing the text through is the whole of this function's
+ * value. MySQL compares a string to a `DOUBLE` by coercing the string — `'abc'`
+ * becomes `0` — so `mileage >= abc` is not an error, it is `mileage >= 0`, and it
+ * comes back as a full page of rows that look filtered. The same is true of a
+ * date that does not parse.
+ */
+export declare function coerceFilterValue(type: ScalarType, value: string): {
+    ok: true;
+    value: string | number | boolean | Date;
+} | {
+    ok: false;
+    problem: string;
+};

package/dist/catalog.filters.js

@@ -0,0 +1,272 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CATALOG_FILTER_LIMIT = exports.VALUELESS_FILTER_OPERATORS = exports.CATALOG_FILTER_OPERATORS = void 0;
+exports.isCatalogFilterOperator = isCatalogFilterOperator;
+exports.filterOperatorTakesValue = filterOperatorTakesValue;
+exports.filterOperatorsFor = filterOperatorsFor;
+exports.offeredFilterOperators = offeredFilterOperators;
+exports.encodeObjectFilter = encodeObjectFilter;
+exports.parseObjectFilter = parseObjectFilter;
+exports.resolveObjectFilters = resolveObjectFilters;
+exports.coerceFilterValue = coerceFilterValue;
+/**
+ * Filtering a catalogued type, derived from the type.
+ *
+ * **Nothing here lists a filterable column, and nothing anywhere else may.** The
+ * types this catalog serves are created at runtime — `PUT publish/:type/schema`
+ * writes the properties and the store builds the physical columns from them — so
+ * a hand-maintained list of what is filterable is a list that goes quiet the day
+ * somebody publishes a column nobody edited it for. That is the failure mode this
+ * module exists to remove: the operators a column offers are a function of the
+ * column, computed by {@link filterOperatorsFor}, and both the server (deciding
+ * what it will accept) and the console (deciding what to draw) call that one
+ * function. A screen offering a control the server would refuse, or refusing one
+ * the server would take, is then not expressible.
+ *
+ * This is also why `@dudousxd/nestjs-filter` is not what is used here. That
+ * library derives its filters from entities and routes known at compile time, and
+ * these types do not exist at compile time.
+ *
+ * **The module is pure and imports nothing but types**, because it ships to the
+ * browser through `@dudousxd/nestjs-catalog/client` — the same reason
+ * `validateWorkflow` does. A second copy of the derivation living in the console
+ * is exactly the drift that entry point exists to prevent.
+ */
+/**
+ * Every operator, in the order a control should offer them.
+ *
+ * One list, so nothing narrows a stored or transmitted operator against a second
+ * hand-maintained copy of these names — the same argument
+ * `CATALOG_SNAPSHOT_MODES` makes one file over.
+ *
+ * There is no `between`. A range is `gte` and `lte` on one property, which is two
+ * filters that compose with everything else rather than one operator that needs
+ * its own wire form, its own second value and its own "what if the ends are the
+ * wrong way round" answer.
+ */
+exports.CATALOG_FILTER_OPERATORS = [
+    'eq',
+    'ne',
+    'contains',
+    'gte',
+    'lte',
+    'gt',
+    'lt',
+    'empty',
+    'notEmpty',
+];
+function isCatalogFilterOperator(value) {
+    return exports.CATALOG_FILTER_OPERATORS.some((operator) => operator === value);
+}
+/**
+ * The operators that take no value.
+ *
+ * "Has no value" cannot be spelled as a comparison — `= NULL` matches nothing in
+ * SQL and `= ''` misses the NULLs — so it is an operator rather than a value a
+ * caller types, and a filter carrying one is complete without a `value`.
+ */
+exports.VALUELESS_FILTER_OPERATORS = ['empty', 'notEmpty'];
+function filterOperatorTakesValue(operator) {
+    return !exports.VALUELESS_FILTER_OPERATORS.some((valueless) => valueless === operator);
+}
+const TEXT_OPERATORS = [
+    'contains',
+    'eq',
+    'ne',
+    'empty',
+    'notEmpty',
+];
+const NUMBER_OPERATORS = [
+    'eq',
+    'ne',
+    'gte',
+    'lte',
+    'gt',
+    'lt',
+    'empty',
+    'notEmpty',
+];
+/**
+ * A date gets the two range ends and nothing else.
+ *
+ * No `eq`, deliberately. These columns are `DATETIME`, and a person filtering a
+ * date types a day — so `= 2026-03-04` compares against midnight and misses every
+ * row loaded at any other second of that day. It looks like "nothing happened on
+ * the 4th", which is the most expensive wrong answer a filter can give. `gte` the
+ * 4th and `lte` the 4th is the same intent expressed in a way that is true.
+ */
+const DATE_OPERATORS = ['gte', 'lte', 'empty', 'notEmpty'];
+const BOOLEAN_OPERATORS = ['eq', 'empty', 'notEmpty'];
+/**
+ * What may be filtered on this column, derived from what the column is.
+ *
+ * An empty list means "not filterable", and there are three ways to get one.
+ *
+ * **Hidden** is the overlay saying a column is not part of the generic UI, and a
+ * filter is generic UI.
+ *
+ * **Classified** is the one worth stating out loud, because the column is
+ * otherwise perfectly filterable and the value is never rendered anyway. It is
+ * excluded for the reason `MikroOrmReadStore.buildWhere` already excludes it from
+ * SEARCH: a predicate over a classified column leaks it through row membership.
+ * Filtering is strictly worse than searching there — `gte`/`lte` let a reader
+ * binary-search a value they may not see, in as many requests as it takes.
+ *
+ * **`json`** because a blob has no useful comparison, and it is already dropped
+ * from the readable columns by `CatalogService.visibleColumns`.
+ */
+function filterOperatorsFor(column) {
+    if (column.hidden === true)
+        return [];
+    if (column.classification)
+        return [];
+    switch (column.type) {
+        case 'number':
+            return [...NUMBER_OPERATORS];
+        case 'date':
+            return [...DATE_OPERATORS];
+        case 'boolean':
+            return [...BOOLEAN_OPERATORS];
+        case 'json':
+            return [];
+        default:
+            // `string`, `uuid` and `unknown`. The warehouse stores all three as text
+            // and the ORM store compares them as strings, so they take the same
+            // operators; `unknown` is a column whose type nobody could derive, and
+            // treating it as text is what every other read path here does with it.
+            return [...TEXT_OPERATORS];
+    }
+}
+/** Which operators a column offers, once the store's own limits are applied. */
+function offeredFilterOperators(column, supported) {
+    return filterOperatorsFor(column).filter((operator) => supported.some((available) => available === operator));
+}
+/**
+ * `property:op:value`, repeated once per filter.
+ *
+ * The value is everything after the second colon, so it may contain colons — a
+ * timestamp does. A property name containing one cannot be addressed by this
+ * form; that is refused by name in {@link resolveObjectFilters} rather than
+ * silently mis-parsed, because a filter that quietly does not apply is a screen
+ * showing every row as though it had been filtered.
+ */
+function encodeObjectFilter(filter) {
+    if (!filterOperatorTakesValue(filter.op))
+        return `${filter.property}:${filter.op}`;
+    return `${filter.property}:${filter.op}:${filter.value ?? ''}`;
+}
+function parseObjectFilter(raw) {
+    const parts = raw.split(':');
+    if (parts.length < 2)
+        return undefined;
+    const [property, op, ...rest] = parts;
+    if (!property || !isCatalogFilterOperator(op))
+        return undefined;
+    if (!filterOperatorTakesValue(op))
+        return { property, op };
+    return { property, op, value: rest.join(':') };
+}
+/**
+ * How many filters one read may carry.
+ *
+ * A cap rather than none, because every filter is another conjunct in the two
+ * statements a paged read issues, and a caller that can send five hundred can
+ * make one request cost whatever it likes. Twenty is far past what a person
+ * builds by hand and far short of anything that would trouble the optimiser.
+ */
+exports.CATALOG_FILTER_LIMIT = 20;
+/**
+ * Turn what arrived into what a store may be given, or say why not.
+ *
+ * **Unhonourable filters are reported, never dropped.** The neighbouring
+ * `parseOutcomes` on the controller drops an unrecognised trace outcome on
+ * purpose, and this goes the other way for a reason that is worth the two
+ * sentences: dropping there costs a filter, so a typo widens the result set and
+ * shows more traces than asked for. Dropping HERE would narrow nothing — the read
+ * would come back unfiltered and the screen would present the whole table as
+ * though it were the matching rows. A filter that silently does not apply is the
+ * one failure mode a filtering UI must not have.
+ *
+ * @param columns the properties this reader may see. Deliberately the visible,
+ * non-blob columns rather than `type.properties`: a filter is only ever resolved
+ * against what the same request would return.
+ */
+function resolveObjectFilters(columns, raw) {
+    const filters = [];
+    const problems = [];
+    if (raw.length > exports.CATALOG_FILTER_LIMIT) {
+        problems.push(`${raw.length} filters were sent and at most ${exports.CATALOG_FILTER_LIMIT} are accepted on one read.`);
+        return { filters, problems };
+    }
+    for (const entry of raw) {
+        const resolved = resolveOne(columns, entry);
+        if ('problem' in resolved)
+            problems.push(resolved.problem);
+        else
+            filters.push(resolved.filter);
+    }
+    return { filters, problems };
+}
+/** One entry: the filter it names, or the sentence explaining why it is not one. */
+function resolveOne(columns, entry) {
+    const parsed = parseObjectFilter(entry);
+    if (!parsed) {
+        return {
+            problem: `"${entry}" is not a filter. The form is property:operator:value, and the operator is one of ${exports.CATALOG_FILTER_OPERATORS.join(', ')}.`,
+        };
+    }
+    const property = columns.find((column) => column.name === parsed.property);
+    if (!property) {
+        return {
+            problem: `${parsed.property} is not a readable property of this type. Filter by a property's name — on a published type that is the identifier form, which is not always how the source spelled the column.`,
+        };
+    }
+    const allowed = filterOperatorsFor(property);
+    if (!allowed.some((operator) => operator === parsed.op)) {
+        return {
+            problem: allowed.length === 0
+                ? `${property.name} cannot be filtered.`
+                : `${property.name} is ${property.type} and cannot be filtered with ${parsed.op}. It takes ${allowed.join(', ')}.`,
+        };
+    }
+    if (!filterOperatorTakesValue(parsed.op))
+        return { filter: { property, op: parsed.op } };
+    const coerced = coerceFilterValue(property.type, parsed.value ?? '');
+    if (!coerced.ok)
+        return { problem: `${property.name}: ${coerced.problem}` };
+    return { filter: { property, op: parsed.op, value: coerced.value } };
+}
+/**
+ * A typed value, or the reason there is none.
+ *
+ * Refusing rather than passing the text through is the whole of this function's
+ * value. MySQL compares a string to a `DOUBLE` by coercing the string — `'abc'`
+ * becomes `0` — so `mileage >= abc` is not an error, it is `mileage >= 0`, and it
+ * comes back as a full page of rows that look filtered. The same is true of a
+ * date that does not parse.
+ */
+function coerceFilterValue(type, value) {
+    if (type === 'number') {
+        const parsed = Number(value);
+        if (value.trim() === '' || !Number.isFinite(parsed)) {
+            return { ok: false, problem: `"${value}" is not a number.` };
+        }
+        return { ok: true, value: parsed };
+    }
+    if (type === 'date') {
+        const parsed = new Date(value);
+        if (Number.isNaN(parsed.getTime())) {
+            return { ok: false, problem: `"${value}" is not a date.` };
+        }
+        return { ok: true, value: parsed };
+    }
+    if (type === 'boolean') {
+        const normalised = value.trim().toLowerCase();
+        if (['true', '1', 'yes'].includes(normalised))
+            return { ok: true, value: true };
+        if (['false', '0', 'no'].includes(normalised))
+            return { ok: true, value: false };
+        return { ok: false, problem: `"${value}" is not true or false.` };
+    }
+    return { ok: true, value };
+}

package/dist/catalog.service.d.ts

@@ -63,6 +63,21 @@ export declare class CatalogService {
     readObjects(typeName: string, query: CatalogObjectQuery & {
         snapshot?: string;
     }): Promise<CatalogObjectPage>;
+    /** What the mounted store can push into a read predicate. Empty when it cannot. */
+    private filterOperators;
+    /**
+     * Every filter, or a refusal naming all of them at once.
+     *
+     * One message listing every problem rather than the first: somebody who built
+     * four filters and got two of them wrong should learn that in one round trip.
+     *
+     * The store is asked whether it can honour the operators before the read runs,
+     * which is what stops a store that does not filter from answering with an
+     * unfiltered page. That refusal is worth more than it costs — a screen only
+     * offers what `filterOperators` reported, so a caller reaching this branch is
+     * one that built the request itself.
+     */
+    private resolveFilters;
     /** Empty when the store keeps no history. */
     listSnapshots(typeName: string): Promise<SnapshotRef[]>;
     /** What the mounted store can do — the screens branch on this. */

package/dist/catalog.service.js

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CatalogService = void 0;
 const common_1 = require("@nestjs/common");
 const catalog_events_1 = require("./catalog.events");
+const catalog_filters_1 = require("./catalog.filters");
 const catalog_options_1 = require("./catalog.options");
 const catalog_query_1 = require("./catalog.query");
 const catalog_query_cache_1 = require("./catalog.query-cache");
@@ -130,14 +131,24 @@ let CatalogService = class CatalogService {
         // Sort is validated here rather than in the store: an unrecognised column
         // must never reach a query builder, whatever the engine.
         const sort = columns.some((c) => c.name === query.sort) ? query.sort : undefined;
-        const { rows, total } = await this.store.read(type, fields, {
+        // Filters, against the same `columns` a sort is checked against and for the
+        // same reason — with one difference in what a failure means. An unrecognised
+        // sort falls back to the primary key, because the rows are the same rows in a
+        // different order. An unrecognised filter cannot fall back to anything: the
+        // read would come back holding rows the caller asked to exclude, and neither
+        // the caller nor the screen has any way to tell.
+        const filters = this.resolveFilters(columns, query.filters ?? []);
+        const result = await this.store.read(type, fields, {
             page,
             size,
             search: query.search,
             sort,
             dir: query.dir === 'desc' ? 'desc' : 'asc',
             snapshot: query.snapshot,
+            ...(filters.length > 0 ? { filters } : {}),
         });
+        const { rows, total } = result;
+        const storeOperators = this.filterOperators();
         return {
             type: type.name,
             page,
@@ -150,10 +161,52 @@ let CatalogService = class CatalogService {
                 type: c.type,
                 classification: c.classification,
                 unit: c.unit,
+                columnName: c.columnName,
+                // What this deployment will actually accept for this column: the rule
+                // derived from the column, narrowed by what the mounted store can do.
+                // Sent per column so a console needs no second request and no table of
+                // its own — see `catalog.filters.ts` on why a hand-kept list is the
+                // failure mode being avoided.
+                filterOperators: (0, catalog_filters_1.offeredFilterOperators)(c, storeOperators),
             })),
             rows,
+            ...(result.snapshot ? { snapshot: result.snapshot } : {}),
         };
     }
+    /** What the mounted store can push into a read predicate. Empty when it cannot. */
+    filterOperators() {
+        return (0, catalog_store_1.supportsObjectFilters)(this.store) ? this.store.objectFilterOperators : [];
+    }
+    /**
+     * Every filter, or a refusal naming all of them at once.
+     *
+     * One message listing every problem rather than the first: somebody who built
+     * four filters and got two of them wrong should learn that in one round trip.
+     *
+     * The store is asked whether it can honour the operators before the read runs,
+     * which is what stops a store that does not filter from answering with an
+     * unfiltered page. That refusal is worth more than it costs — a screen only
+     * offers what `filterOperators` reported, so a caller reaching this branch is
+     * one that built the request itself.
+     */
+    resolveFilters(columns, raw) {
+        if (raw.length === 0)
+            return [];
+        const { filters, problems } = (0, catalog_filters_1.resolveObjectFilters)(columns, raw);
+        const supported = this.filterOperators();
+        const unsupported = filters
+            .map((filter) => filter.op)
+            .filter((op) => !supported.some((available) => available === op));
+        if (unsupported.length > 0) {
+            throw new common_1.BadRequestException(supported.length === 0
+                ? "This catalog's store does not filter object reads, so it can only be paged, searched and sorted."
+                : `This catalog's store cannot filter with ${[...new Set(unsupported)].join(', ')}. It applies ${supported.join(', ')}.`);
+        }
+        if (problems.length > 0) {
+            throw new common_1.BadRequestException(problems.join(' '));
+        }
+        return filters;
+    }
     /** Empty when the store keeps no history. */
     async listSnapshots(typeName) {
         const type = this.registry.getType(typeName);

package/dist/catalog.store.d.ts

@@ -1,4 +1,5 @@
 import { BadRequestException } from '@nestjs/common';
+import type { CatalogFilterOperator, CatalogResolvedFilter } from './catalog.filters';
 import type { CatalogObjectQuery, CatalogObjectTypeDef } from './catalog.types';
 /**
  * Where the objects actually live.
@@ -149,14 +150,74 @@ export interface CatalogStoreCapabilities {
  * into a boot failure.
  */
 export declare function isCatalogStoreCapabilities(value: unknown): value is CatalogStoreCapabilities;
-export interface CatalogReadQuery extends CatalogObjectQuery {
+/**
+ * What a store is asked for, once the service has vetted it.
+ *
+ * `Omit<..., 'filters'>` and not a plain extension, and the omission is the
+ * point: `CatalogObjectQuery.filters` is the caller's raw
+ * `property:operator:value` text, and a store must never be handed one. What
+ * arrives here instead is {@link CatalogResolvedFilter}, whose property is the
+ * type's own definition — so the column a predicate is built from came off the
+ * type rather than off the request, and the type system says so rather than a
+ * comment. `sort` is a bare string only because every store already re-matches it
+ * against the type before using it; a filter carries more than a name, so
+ * resolving it once in the service is both cheaper and harder to get wrong.
+ */
+export interface CatalogReadQuery extends Omit<CatalogObjectQuery, 'filters'> {
     /** Read as of a specific snapshot. Ignored when `timeTravel` is false. */
     snapshot?: string;
+    /**
+     * Every one of these must be applied. A store that cannot apply one must not
+     * silently return the rows it would have returned anyway — declare the
+     * operators it can honour (see {@link CatalogFilteringReadStore}) and the
+     * service will refuse the read instead.
+     */
+    filters?: CatalogResolvedFilter[];
 }
 export interface CatalogReadResult {
     rows: Array<Record<string, unknown>>;
     total: number;
+    /**
+     * Which snapshot these rows came from, and whether it is the one being served.
+     *
+     * Answered by the store because the store is what resolved it: a read that was
+     * given no snapshot falls back to the pointer, so only the store knows which id
+     * the rows actually carry. Reporting it costs nothing — every store that keeps
+     * history has already read both values by the time it builds the query — and it
+     * is what lets a screen say "this is not the current load" on the strength of
+     * what was read rather than of what it thinks it asked for.
+     *
+     * Absent from a store that keeps no history, which is the honest answer there:
+     * the rows are the current state and there is no other state to be reading.
+     */
+    snapshot?: {
+        id: string;
+        current: boolean;
+    };
+}
+/**
+ * A store that applies {@link CatalogReadQuery.filters}.
+ *
+ * Declared, never assumed, and the reason is the same one the capability object
+ * one file up gives for every field on it: a store that ignores a filter answers
+ * with more rows than were asked for, and there is nothing about that answer to
+ * distinguish it from a filter that genuinely matched everything. So a store says
+ * which operators it can push into its predicate, the service offers exactly
+ * those to the screen, and a filter naming anything else is refused rather than
+ * quietly dropped.
+ *
+ * A guard rather than a field on `CatalogStoreCapabilities`, deliberately: the
+ * capability object is intersected by the fan-out through an exhaustiveness check
+ * that fails to compile when a field is added and not composed, and this is not a
+ * property that composes the way those do — a fan-out reads through its primary,
+ * so what its primary can filter is what it can filter. Asking the object it
+ * holds is the check that stays true when that changes.
+ */
+export interface CatalogFilteringReadStore extends CatalogReadStore {
+    /** Which operators this store can apply. A subset of `CATALOG_FILTER_OPERATORS`. */
+    readonly objectFilterOperators: readonly CatalogFilterOperator[];
 }
+export declare function supportsObjectFilters(store: unknown): store is CatalogFilteringReadStore;
 /** The minimum a store must do: return rows of a catalogued type. */
 export interface CatalogReadStore {
     readonly capabilities: CatalogStoreCapabilities;

package/dist/catalog.store.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CATALOG_STORE = exports.CatalogColumnCollisionError = exports.UnsafeIdentifierError = exports.CATALOG_RESERVED_COLUMNS = exports.CATALOG_SNAPSHOT_MODES = void 0;
 exports.isCatalogStoreCapabilities = isCatalogStoreCapabilities;
+exports.supportsObjectFilters = supportsObjectFilters;
 exports.isReservedColumn = isReservedColumn;
 exports.isSafeIdentifier = isSafeIdentifier;
 exports.assertSafeIdentifier = assertSafeIdentifier;
@@ -49,6 +50,11 @@ function isCatalogStoreCapabilities(value) {
     }
     return true;
 }
+function supportsObjectFilters(store) {
+    return (typeof store === 'object' &&
+        store !== null &&
+        Array.isArray(Reflect.get(store, 'objectFilterOperators')));
+}
 /**
  * The columns a snapshot-emulating store adds to every object table.
  *

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

@@ -15,6 +15,24 @@ 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;
@@ -39,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

package/dist/client.js

@@ -11,7 +11,7 @@
  * types are.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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.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
@@ -19,6 +19,33 @@ exports.pipelineExpectationRoutes = pipelineExpectationRoutes;
 // 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

package/dist/index.d.ts

@@ -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, assertSafeIdentifier, 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, isSafeIdentifier, isWriteStore, type SnapshotRef, supportsCarryForward, UnsafeIdentifierError, } 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

@@ -15,7 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 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.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;
+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; } });
@@ -132,6 +132,13 @@ 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; } });
@@ -139,6 +146,7 @@ Object.defineProperty(exports, "CATALOG_RESERVED_COLUMNS", { enumerable: true, g
 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; } });

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.13.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",