@dudousxd/nestjs-catalog 0.13.0 → 0.15.0

package/dist/catalog.service.js

@@ -11,10 +11,12 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+var CatalogService_1;
 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");
@@ -24,6 +26,17 @@ const catalog_workspace_1 = require("./catalog.workspace");
 const search_1 = require("./search");
 const DEFAULT_PAGE_SIZE = 25;
 const DEFAULT_MAX_PAGE_SIZE = 200;
+/**
+ * A finished array, seen as the shape a streamed read has.
+ *
+ * Yields out of the caller's array rather than copying it: the rows are already
+ * held by whoever produced them, and a second copy would be the cost this whole
+ * path exists to avoid, paid on the one code path that could least afford it.
+ */
+async function* fromRows(rows) {
+    for (const row of rows)
+        yield row;
+}
 /**
  * Reads objects of any catalogued type through one endpoint.
  *
@@ -33,7 +46,7 @@ const DEFAULT_MAX_PAGE_SIZE = 200;
  * new store cannot accidentally relax them — the appeal of a generic read
  * endpoint is also its whole risk.
  */
-let CatalogService = class CatalogService {
+let CatalogService = CatalogService_1 = class CatalogService {
     registry;
     store;
     options;
@@ -45,6 +58,7 @@ let CatalogService = class CatalogService {
         this.workspace = workspace;
     }
     cache = new catalog_query_cache_1.QueryCache();
+    logger = new common_1.Logger(CatalogService_1.name);
     // ---------------------------------------------------------------------------
     // The facade.
     //
@@ -130,14 +144,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 +174,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);
@@ -366,6 +432,63 @@ let CatalogService = class CatalogService {
         });
         return { savedQuery: saved, result };
     }
+    /**
+     * The same saved query, as rows arriving rather than a result.
+     *
+     * For the export route, and it differs from {@link runSavedQuery} in three
+     * ways that are all the same decision seen from different sides.
+     *
+     * **No cap when the store streams.** An export is the whole result by
+     * definition — that is what distinguishes it from the table it was exported
+     * from — so `maxQueryRows` is not applied. It cannot be: a capped export is a
+     * prefix handed over as a complete file, with nothing in the file to say so.
+     *
+     * **No cache, in either direction.** Nothing is read from it, because what it
+     * holds is a *capped* page and serving that would silently truncate; and
+     * nothing is written to it, because the thing being produced is the object the
+     * cache exists to avoid holding.
+     *
+     * **No timeout.** {@link CatalogModuleOptions.queryTimeoutMs} bounds a
+     * statement somebody is waiting on behind a screen. An export of a large table
+     * runs for as long as the table takes, and the bound that matters is that
+     * neither this process nor the driver holds more than a row — which the stream
+     * is what provides. A client that gives up closes the connection, and the
+     * consumer stopping its pull is what releases the read.
+     *
+     * **A store that cannot stream falls back to the capped buffered read**, and
+     * that is a real difference in what the same route returns depending on what
+     * is mounted underneath. It is the honest option: lifting the cap on a store
+     * that materialises its result set would not make the export complete, it
+     * would move the failure into the driver, where there is no cap to report. The
+     * truncation is logged, since a CSV has nowhere to carry the fact.
+     */
+    async streamSavedQuery(id) {
+        const saved = await this.getSavedQuery(id);
+        if (!(0, catalog_query_1.isQueryStore)(this.store)) {
+            throw new common_1.BadRequestException("This catalog's store does not support SQL queries.");
+        }
+        try {
+            (0, catalog_query_1.assertReadOnlyShape)(saved.sql);
+        }
+        catch (error) {
+            throw new common_1.BadRequestException(error instanceof Error ? error.message : String(error));
+        }
+        if ((0, catalog_query_1.isStreamingQueryStore)(this.store)) {
+            // Columns are left undefined: a streamed read learns them from its first
+            // row, exactly as the buffered one does from `rows[0]`.
+            return { savedQuery: saved, rows: this.store.streamQuery({ sql: saved.sql }) };
+        }
+        const cap = this.options.maxQueryRows ?? 1_000;
+        const result = await this.store.runQuery({
+            sql: saved.sql,
+            maxRows: cap,
+            timeoutMs: this.options.queryTimeoutMs ?? 15_000,
+        });
+        if (result.truncated) {
+            this.logger.warn(`Exported saved query ${saved.id} ("${saved.name}") was cut off at ${cap} rows: the mounted store cannot stream a result, so the export is bounded by maxQueryRows. The downloaded file is a prefix and says nothing about it.`);
+        }
+        return { savedQuery: saved, columns: result.columns, rows: fromRows(result.rows) };
+    }
     listDashboards() {
         return this.workspace ? this.workspace.listDashboards() : Promise.resolve([]);
     }
@@ -608,7 +731,7 @@ let CatalogService = class CatalogService {
     }
 };
 exports.CatalogService = CatalogService;
-exports.CatalogService = CatalogService = __decorate([
+exports.CatalogService = CatalogService = CatalogService_1 = __decorate([
     (0, common_1.Injectable)(),
     __param(1, (0, common_1.Inject)(catalog_store_1.CATALOG_STORE)),
     __param(2, (0, common_1.Inject)(catalog_options_1.CATALOG_OPTIONS)),

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;
@@ -346,30 +407,31 @@ export declare const CATALOG_RESERVED_COLUMNS: readonly ["_snapshot_id", "_princ
 export type CatalogReservedColumn = (typeof CATALOG_RESERVED_COLUMNS)[number];
 export declare function isReservedColumn(column: string): boolean;
 /**
- * Why a name cannot be written into SQL, in the words a publisher is given.
+ * The whole naming rule, which used to be written out here.
  *
- * One class for the whole ecosystem rather than one per adapter, so
- * `instanceof` is a usable question across packages. The publish-time check in
- * the pipeline package catches this to tell "that name cannot be an identifier"
- * from "something else failed inside the store", and with a class per adapter
- * that check would re-throw the moment the mounted store was not the one it
- * imported — turning a 400 that names the property into a 500 that names
- * nothing.
- */
-export declare class UnsafeIdentifierError extends Error {
-    constructor(value: string);
-}
-/** Whether a name can be written into SQL as it stands. */
-export declare function isSafeIdentifier(value: string): boolean;
-/**
- * Refuse a name that cannot be a SQL identifier.
+ * `isSafeIdentifier` and friends, the {@link physicalColumn} cleaning and the
+ * {@link outputAlias} it feeds all moved to `catalog.identifiers.ts` — a file
+ * that imports nothing — and are re-exported here so that every caller that
+ * reached them from this module still does.
+ *
+ * The move was not tidying. This file imports `BadRequestException` at module
+ * scope, so a browser importing a *value* from it would pull NestJS into its
+ * bundle, and a console proposing to replicate a table has to be able to ask,
+ * before it draws anything, whether the source's column spellings could be
+ * published as property names. The question a publisher is refused on is
+ * `isSafeIdentifier(physicalColumn(name))`, so both halves had to become
+ * reachable from `/client`, answered by the same two functions the DDL runs
+ * rather than by a copy of either. See the docblock on `catalog.identifiers.ts`.
  *
- * Throws rather than answering, because the caller's next line writes the value
- * into a statement: a boolean that can be ignored is a boolean that eventually
- * is. {@link isSafeIdentifier} is there for the callers that are asking rather
- * than about to build.
+ * A bare `export … from` and not `import` + `export`, which is safe here for a
+ * reason worth writing down: nothing left in this file *calls* any of them.
+ * A re-export forwards a name without binding it locally, and while `outputAlias`
+ * still lived here — one line, calling `isSafeIdentifier` — that difference was
+ * a `ReferenceError` at the first read of any type, compiled and shipped by a
+ * rebase that had nothing to conflict on. Adding a caller here means turning
+ * this back into an import.
  */
-export declare function assertSafeIdentifier(value: string): void;
+export { assertSafeIdentifier, isSafeIdentifier, outputAlias, physicalColumn, UnsafeIdentifierError, } from './catalog.identifiers';
 /** One property, and the column it cannot have. */
 export interface CatalogColumnCollision {
     /** `reserved` — it lands on a store column. `shared` — two properties collide. */

package/dist/catalog.store.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATALOG_STORE = exports.CatalogColumnCollisionError = exports.UnsafeIdentifierError = exports.CATALOG_RESERVED_COLUMNS = exports.CATALOG_SNAPSHOT_MODES = void 0;
+exports.CATALOG_STORE = exports.CatalogColumnCollisionError = exports.UnsafeIdentifierError = exports.physicalColumn = exports.outputAlias = exports.isSafeIdentifier = exports.assertSafeIdentifier = 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;
 exports.findColumnCollisions = findColumnCollisions;
 exports.assertNoColumnCollisions = assertNoColumnCollisions;
 exports.isWriteStore = isWriteStore;
@@ -49,6 +48,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.
  *
@@ -75,72 +79,36 @@ function isReservedColumn(column) {
     return exports.CATALOG_RESERVED_COLUMNS.some((reserved) => reserved === column.toLowerCase());
 }
 /**
- * What a name has to look like before a store will write it into SQL.
- *
- * Identifiers are *rejected*, never escaped and never sanitised. Every table
- * and column name a store emits arrives from another application over HTTP and
- * ends up in DDL and in SELECT lists, where no placeholder can stand in for it,
- * so anything outside this character set never becomes SQL at all.
- *
- * Here, beside {@link CATALOG_RESERVED_COLUMNS}, for the same reason: it is
- * part of what the catalog promises a *publisher*. Refuse a property name and
- * the sentence explaining why is the only statement of the rule most people
- * will ever read, so it belongs to the contract rather than to whichever
- * adapter happens to be mounted.
- *
- * And for one more reason. It used to be two copies — `store-mikro-orm` and
- * `store-clickhouse` each carried this pattern and this sentence, byte for
- * byte — and the publish-time refusal in the pipeline package borrowed the
- * MySQL one so that publish-time and DDL-time could not disagree about the
- * character set, the length or the wording. That bought the guarantee for a
- * MySQL deployment and left a ClickHouse-only one trusting two files to be
- * edited together. One definition is the guarantee; two identical ones are a
- * habit.
- *
- * 63 characters because it is under MySQL's 64-character ceiling and no engine
- * a store here targets refuses a name that short, and because the number is
- * quoted in the refusal below: a per-store limit would mean a publisher being
- * told a different rule depending on what is mounted, for a name the catalog
- * would then be unable to promise anything about across a fan-out.
- *
- * Not exported. A `RegExp` is mutable and shared state, and the two questions
- * anyone has of it — "may I?" and "why not?" — are {@link isSafeIdentifier} and
- * {@link UnsafeIdentifierError}.
- */
-const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]{0,62}$/;
-/**
- * Why a name cannot be written into SQL, in the words a publisher is given.
- *
- * One class for the whole ecosystem rather than one per adapter, so
- * `instanceof` is a usable question across packages. The publish-time check in
- * the pipeline package catches this to tell "that name cannot be an identifier"
- * from "something else failed inside the store", and with a class per adapter
- * that check would re-throw the moment the mounted store was not the one it
- * imported — turning a 400 that names the property into a 500 that names
- * nothing.
- */
-class UnsafeIdentifierError extends Error {
-    constructor(value) {
-        super(`Refusing to use "${value}" as a SQL identifier: letters, digits and underscore only, starting with a letter or underscore, 63 characters max.`);
-    }
-}
-exports.UnsafeIdentifierError = UnsafeIdentifierError;
-/** Whether a name can be written into SQL as it stands. */
-function isSafeIdentifier(value) {
-    return SAFE_IDENTIFIER.test(value);
-}
-/**
- * Refuse a name that cannot be a SQL identifier.
- *
- * Throws rather than answering, because the caller's next line writes the value
- * into a statement: a boolean that can be ignored is a boolean that eventually
- * is. {@link isSafeIdentifier} is there for the callers that are asking rather
- * than about to build.
+ * The whole naming rule, which used to be written out here.
+ *
+ * `isSafeIdentifier` and friends, the {@link physicalColumn} cleaning and the
+ * {@link outputAlias} it feeds all moved to `catalog.identifiers.ts` — a file
+ * that imports nothing — and are re-exported here so that every caller that
+ * reached them from this module still does.
+ *
+ * The move was not tidying. This file imports `BadRequestException` at module
+ * scope, so a browser importing a *value* from it would pull NestJS into its
+ * bundle, and a console proposing to replicate a table has to be able to ask,
+ * before it draws anything, whether the source's column spellings could be
+ * published as property names. The question a publisher is refused on is
+ * `isSafeIdentifier(physicalColumn(name))`, so both halves had to become
+ * reachable from `/client`, answered by the same two functions the DDL runs
+ * rather than by a copy of either. See the docblock on `catalog.identifiers.ts`.
+ *
+ * A bare `export … from` and not `import` + `export`, which is safe here for a
+ * reason worth writing down: nothing left in this file *calls* any of them.
+ * A re-export forwards a name without binding it locally, and while `outputAlias`
+ * still lived here — one line, calling `isSafeIdentifier` — that difference was
+ * a `ReferenceError` at the first read of any type, compiled and shipped by a
+ * rebase that had nothing to conflict on. Adding a caller here means turning
+ * this back into an import.
  */
-function assertSafeIdentifier(value) {
-    if (!isSafeIdentifier(value))
-        throw new UnsafeIdentifierError(value);
-}
+var catalog_identifiers_1 = require("./catalog.identifiers");
+Object.defineProperty(exports, "assertSafeIdentifier", { enumerable: true, get: function () { return catalog_identifiers_1.assertSafeIdentifier; } });
+Object.defineProperty(exports, "isSafeIdentifier", { enumerable: true, get: function () { return catalog_identifiers_1.isSafeIdentifier; } });
+Object.defineProperty(exports, "outputAlias", { enumerable: true, get: function () { return catalog_identifiers_1.outputAlias; } });
+Object.defineProperty(exports, "physicalColumn", { enumerable: true, get: function () { return catalog_identifiers_1.physicalColumn; } });
+Object.defineProperty(exports, "UnsafeIdentifierError", { enumerable: true, get: function () { return catalog_identifiers_1.UnsafeIdentifierError; } });
 /**
  * Every way a type's properties would fight over a physical column.
  *

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,59 @@ export interface CatalogObjectPage {
         type: ScalarType;
         classification?: string;
         unit?: string;
+        /**
+         * How the source spells this column, when it is not how the property is
+         * named.
+         *
+         * Lineage, and only lineage — nothing reads a record through it. A reader
+         * recognises the source spelling because it is what is on their spreadsheet,
+         * and a filter has to be built from the property name, so both are here and a
+         * screen can show one and send the other.
+         *
+         * The two differ less often than they used to. A property may now be named
+         * `Asset Id` outright: a store cleans the name to reach its column and
+         * aliases its view to the cleaned form, so a name is no longer required to be
+         * a SQL identifier. Publishers were previously told to send `{ name:
+         * 'Asset_Id', columnName: 'Asset Id' }`, which is where most of the divergent
+         * pairs in an older catalog come from — and it was a costly instruction,
+         * because a load matches records to properties by NAME, so those columns
+         * loaded NULL. The two still differ whenever a publisher chooses different
+         * names for its own reasons, which is why the field stays.
+         *
+         * 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,54 @@ 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';
+/**
+ * How a name becomes a column, shipped to the browser deliberately.
+ *
+ * The second exception to "types only" on this entry point, and it is made for
+ * the same reason `validateWorkflow` is the first: the answer has to be the
+ * same one the server will give, and the only way to guarantee that is for both
+ * to run these functions.
+ *
+ * A console proposing to replicate a table has to be able to ask, *before* it
+ * draws anything, whether the source's own column spellings could be published
+ * as property names — because a property `name` is what the warehouse looks
+ * every field up by, `row[property.name]`, so a name the publisher then refuses
+ * has to be renamed, and a rename with nothing renaming the record's keys to
+ * match writes null into that column on every run and reports success. That is
+ * not a hypothesis; it is what happened to six types in one evening.
+ *
+ * **Both halves, because the composition is the rule.** A name no longer has to
+ * be an identifier itself — the view's output alias and the read's lookup key go
+ * through {@link outputAlias} together, so `Asset Id` is a perfectly good
+ * property name and lands in `Asset_Id`. What is still refused is a name whose
+ * *cleaned* form is not an identifier: `2024 Total` cleans to `2024_Total`, and
+ * no store will quote a name starting with a digit. So the question worth asking
+ * from a browser is `isSafeIdentifier(physicalColumn(name))` — the same two
+ * calls, in the same order, that `identifierRefusal` makes at publish time.
+ * Exporting only `isSafeIdentifier` would let a console answer the stricter,
+ * obsolete question and refuse a graph the server would have accepted.
+ *
+ * Safe to export because `catalog.identifiers.ts` imports nothing at all.
+ */
+export { isSafeIdentifier, outputAlias, physicalColumn, UnsafeIdentifierError, } from './catalog.identifiers';
 /** What a tier-0 edit to a type may change. */
 export interface TypePatch {
     displayName?: string;
@@ -39,6 +87,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
@@ -85,8 +153,8 @@ export declare const catalogRoutes: {
     readonly traces: () => string;
     readonly trace: (id: string) => string;
 };
-export type { CatalogConnection, CatalogConnector, ConnectionCheck, CatalogTransform, CatalogWorkflow, CatalogWorkflowCapabilities, ConnectorKind, ConnectorRun, TransformLanguage, TransformResult, WorkflowEdge, WorkflowExecutionMode, WorkflowGraph, WorkflowIssueCode, WorkflowNode, WorkflowNodeKind, WorkflowNodeOutcome, WorkflowSinkNode, WorkflowSourceNode, WorkflowStageRef, WorkflowTransformNode, WorkflowValidationIssue, } from './catalog.pipeline';
-export { CONNECTOR_KINDS, isConnectorKind, isTransformLanguage, isWorkflowEdge, isWorkflowNode, TRANSFORM_LANGUAGES, } from './catalog.pipeline';
+export type { CatalogConnection, CatalogConnector, ConnectionCheck, CatalogTransform, CatalogWorkflow, CatalogWorkflowCapabilities, ConnectorKind, ConnectorRun, TransformLanguage, TransformResult, CallableWorkflowRef, WorkflowCallEnvelope, WorkflowCallNode, WorkflowCallOutput, WorkflowEdge, WorkflowExecutionMode, WorkflowGraph, WorkflowIssueCode, WorkflowNode, WorkflowNodeKind, WorkflowNodeOutcome, WorkflowSinkNode, WorkflowSourceNode, WorkflowStageRef, WorkflowTransformNode, WorkflowValidationIssue, } from './catalog.pipeline';
+export { CONNECTOR_KINDS, isConnectorKind, isTransformLanguage, isWorkflowEdge, isWorkflowNode, TRANSFORM_LANGUAGES, readWorkflowCallOutput, WORKFLOW_CALL_CONTRACT, } from './catalog.pipeline';
 /**
  * The workflow validator, shipped to the browser deliberately.
  *