@dudousxd/nestjs-catalog 0.12.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.events.d.ts

@@ -106,10 +106,17 @@ export interface CatalogEventPayloads {
         snapshotId: string;
     };
     /**
-     * Someone changed a label, description, unit or visibility.
+     * Someone changed a label, description, unit or visibility — or stated how a
+     * type reconciles deletes.
      *
-     * Presentation-only, and emitted anyway: "who renamed this column and when"
-     * is a governance question, and the answer is otherwise nowhere.
+     * Presentation was the whole of it once, and emitted anyway: "who renamed this
+     * column and when" is a governance question whose answer is otherwise nowhere.
+     * Per-type load expectations then arrived on the same event, and a delete
+     * strategy is not presentation — it decides whether an incremental load of the
+     * type may commit at all. `changed` tells the two apart (`expectation.deletes`
+     * and `expectation.cleared` against the field names a rename carries), which is
+     * why widening this event was better than minting a second one nobody's
+     * recorder would have been reading.
      */
     'type.curated': {
         typeName: string;

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 };
+}