@dudousxd/nestjs-catalog 0.13.0 → 0.15.0

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.identifiers.d.ts

@@ -0,0 +1,161 @@
+/**
+ * How a name becomes a column, and what it has to look like by the end.
+ *
+ * Two rules, and they are here together because neither is usable without the
+ * other. {@link physicalColumn} is the *cleaning* — the lossy map from a
+ * property's name to the column a store creates for it. {@link isSafeIdentifier}
+ * is the *character set* the result of that cleaning has to be in. What a
+ * publisher is actually promised is the composition: a name may be spelled
+ * however the source spells it, and what the cleaning produces has to be
+ * something a store can write.
+ *
+ * Identifiers themselves are *rejected*, never escaped. 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.
+ *
+ * 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.
+ *
+ * ---
+ *
+ * **Why this is its own module, and why it imports nothing.**
+ *
+ * All of this used to live in `catalog.store.ts`, which is still where every
+ * server-side caller reaches it from — that file re-exports all five names, so no
+ * import anywhere had to change. What could not stay there is the
+ * *reachability*: `catalog.store.ts` imports `BadRequestException` from
+ * `@nestjs/common` at module scope, so anything importing a **value** out of it
+ * drags NestJS along. That is fine on the server and disqualifying for
+ * `/client`, which exists precisely so a browser can share the server's rules
+ * without shipping the server.
+ *
+ * And a browser now has to be able to ask this question. A workflow template
+ * that proposes replicating a table has to know, while somebody is still
+ * choosing, whether the source's column names could be published as property
+ * names — because if they could not, the graph it would draw is refused at
+ * publish, or worse, gets "fixed" by a rename that commits nulls and reports
+ * success. Answering that from a copy of the pattern is the one thing this
+ * module's own history says not to do: the copy is what drifts, and a canvas
+ * whose idea of a legal name differs from the store's by one character is a
+ * canvas that promises a load the publisher then refuses.
+ *
+ * That is why {@link physicalColumn} had to come along rather than only
+ * {@link isSafeIdentifier}. The question a publisher is refused on is
+ * `isSafeIdentifier(physicalColumn(name))`, not `isSafeIdentifier(name)`, and a
+ * browser holding only half the composition would answer a different question
+ * from the server's — which is the same drift by another route.
+ *
+ * So the rule moved to a file with no imports, and is exported from both entry
+ * points. `validateWorkflow` set the precedent and made the same argument.
+ */
+/**
+ * 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.
+ */
+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.
+ *
+ * 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.
+ */
+export declare function assertSafeIdentifier(value: string): void;
+/**
+ * A property's name, cleaned into the column a store can create for it.
+ *
+ * Here rather than in each adapter for the reason {@link assertSafeIdentifier}
+ * is: this is no longer only an adapter's private repair. It decides the column
+ * a load's values are written to, the column a filter is applied to, the name a
+ * committed view exposes the field under, and — since it does all of that — it
+ * decides whether a published name can work at all. The pipeline package refuses
+ * a name at publish time by asking whether *this* produces an identifier, so the
+ * refusal and the DDL have to be running the same cleaning rather than two
+ * copies of it. `store-mikro-orm` and `store-clickhouse` each carried a
+ * byte-identical private copy, and `store-mikro-orm` carried two of its own —
+ * one in `query.ts` for the view, one in `mysql-warehouse.store.ts` for
+ * everything else. Three copies of the function that decides where a column's
+ * data lives is three chances for a view to point at a column no load ever
+ * wrote.
+ *
+ * Lossy on purpose, and lossy in a way callers must handle rather than assume
+ * away: `Asset Id` and `Asset/Id` both clean to `Asset_Id`, which is what
+ * `assertNoColumnCollisions` exists to catch.
+ *
+ * 60 characters, not the 63 the identifier rule allows, and the three characters
+ * of headroom are not decorative — a store that needs to derive a second name
+ * from a column has room inside MySQL's 64-character ceiling to do it. Widening
+ * this would silently rename the column of every property whose name is 61 to 63
+ * characters long, so it stays where it is.
+ *
+ * Not every output is an identifier: `1 2 3` cleans to `1_2_3`, which no store
+ * will quote. That is not this function's business to fix — a suggestion is
+ * `toPhysicalName` in an adapter, and a refusal is `assertSafeIdentifier` on the
+ * result.
+ */
+export declare function physicalColumn(propertyName: string): string;
+/**
+ * The column name a store exposes a property under, in the committed view and
+ * in the SELECT list of a read.
+ *
+ * **Why this is not simply the property's name.** It used to be. Every store
+ * wrote `\`Asset_Id\` AS \`Asset Id\`` — the physical column reached by cleaning,
+ * the alias taken verbatim — and the alias went through `ident`, which refuses
+ * rather than escapes. So a property could only be named something that was
+ * already a SQL identifier, which meant a source column genuinely called `Asset
+ * Id` could not be published under its own spelling.
+ *
+ * That mattered far more than it looks. A load matches a source's record to a
+ * property by property NAME — the store reads `row[property.name]` — so a
+ * publisher forced to rename the property to `Asset_Id`, keeping `Asset Id` in
+ * `columnName`, was publishing a type whose every read of that field returned
+ * `undefined`. `columnName` is lineage; nothing consults it on the write path.
+ * The loads committed, the row counts were right, and the column was NULL in
+ * every row. Thirteen types were loaded that way and six of them came out with
+ * most of their columns empty — 73 of 84 on the largest, across 313,833 rows.
+ * The verbatim alias is what forced the rename, so the alias is what changed.
+ *
+ * **Why the name is still kept when it is already an identifier.** The obvious
+ * fix — always alias to {@link physicalColumn} — would rename the output column
+ * of every existing view whose property name is not equal to its own cleaned
+ * form: a property called `Asset__Id` (two underscores collapse to one) or one
+ * 61 characters long (cut to 60). Those views work today and somebody is
+ * selecting from them by name. Renaming a column under a working consumer to
+ * tidy up an inconsistency is not a trade worth making, so the rule is the
+ * narrower one: **a name that SQL can take as it stands is kept exactly; only a
+ * name SQL cannot take is cleaned.** Every view that resolves today keeps every
+ * column name it has today.
+ *
+ * **This introduces no new way for two properties to collide.** If two distinct
+ * names produce one alias then they also produce one {@link physicalColumn}, so
+ * `assertNoColumnCollisions` already refuses the pair. Both unsafe: equal
+ * aliases *are* equal physical columns. Both safe: equal aliases are equal
+ * names, and there is only one property per name. One of each — a safe `x` and
+ * an unsafe `y` with `physicalColumn(y) === x` — means `x` contains no run of
+ * underscores and is at most 60 characters, so `physicalColumn(x) === x ===
+ * physicalColumn(y)` and the columns collide too.
+ */
+export declare function outputAlias(propertyName: string): string;

package/dist/catalog.identifiers.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * How a name becomes a column, and what it has to look like by the end.
+ *
+ * Two rules, and they are here together because neither is usable without the
+ * other. {@link physicalColumn} is the *cleaning* — the lossy map from a
+ * property's name to the column a store creates for it. {@link isSafeIdentifier}
+ * is the *character set* the result of that cleaning has to be in. What a
+ * publisher is actually promised is the composition: a name may be spelled
+ * however the source spells it, and what the cleaning produces has to be
+ * something a store can write.
+ *
+ * Identifiers themselves are *rejected*, never escaped. 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.
+ *
+ * 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.
+ *
+ * ---
+ *
+ * **Why this is its own module, and why it imports nothing.**
+ *
+ * All of this used to live in `catalog.store.ts`, which is still where every
+ * server-side caller reaches it from — that file re-exports all five names, so no
+ * import anywhere had to change. What could not stay there is the
+ * *reachability*: `catalog.store.ts` imports `BadRequestException` from
+ * `@nestjs/common` at module scope, so anything importing a **value** out of it
+ * drags NestJS along. That is fine on the server and disqualifying for
+ * `/client`, which exists precisely so a browser can share the server's rules
+ * without shipping the server.
+ *
+ * And a browser now has to be able to ask this question. A workflow template
+ * that proposes replicating a table has to know, while somebody is still
+ * choosing, whether the source's column names could be published as property
+ * names — because if they could not, the graph it would draw is refused at
+ * publish, or worse, gets "fixed" by a rename that commits nulls and reports
+ * success. Answering that from a copy of the pattern is the one thing this
+ * module's own history says not to do: the copy is what drifts, and a canvas
+ * whose idea of a legal name differs from the store's by one character is a
+ * canvas that promises a load the publisher then refuses.
+ *
+ * That is why {@link physicalColumn} had to come along rather than only
+ * {@link isSafeIdentifier}. The question a publisher is refused on is
+ * `isSafeIdentifier(physicalColumn(name))`, not `isSafeIdentifier(name)`, and a
+ * browser holding only half the composition would answer a different question
+ * from the server's — which is the same drift by another route.
+ *
+ * So the rule moved to a file with no imports, and is exported from both entry
+ * points. `validateWorkflow` set the precedent and made the same argument.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsafeIdentifierError = void 0;
+exports.isSafeIdentifier = isSafeIdentifier;
+exports.assertSafeIdentifier = assertSafeIdentifier;
+exports.physicalColumn = physicalColumn;
+exports.outputAlias = outputAlias;
+/**
+ * 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.
+ */
+function assertSafeIdentifier(value) {
+    if (!isSafeIdentifier(value))
+        throw new UnsafeIdentifierError(value);
+}
+/**
+ * A property's name, cleaned into the column a store can create for it.
+ *
+ * Here rather than in each adapter for the reason {@link assertSafeIdentifier}
+ * is: this is no longer only an adapter's private repair. It decides the column
+ * a load's values are written to, the column a filter is applied to, the name a
+ * committed view exposes the field under, and — since it does all of that — it
+ * decides whether a published name can work at all. The pipeline package refuses
+ * a name at publish time by asking whether *this* produces an identifier, so the
+ * refusal and the DDL have to be running the same cleaning rather than two
+ * copies of it. `store-mikro-orm` and `store-clickhouse` each carried a
+ * byte-identical private copy, and `store-mikro-orm` carried two of its own —
+ * one in `query.ts` for the view, one in `mysql-warehouse.store.ts` for
+ * everything else. Three copies of the function that decides where a column's
+ * data lives is three chances for a view to point at a column no load ever
+ * wrote.
+ *
+ * Lossy on purpose, and lossy in a way callers must handle rather than assume
+ * away: `Asset Id` and `Asset/Id` both clean to `Asset_Id`, which is what
+ * `assertNoColumnCollisions` exists to catch.
+ *
+ * 60 characters, not the 63 the identifier rule allows, and the three characters
+ * of headroom are not decorative — a store that needs to derive a second name
+ * from a column has room inside MySQL's 64-character ceiling to do it. Widening
+ * this would silently rename the column of every property whose name is 61 to 63
+ * characters long, so it stays where it is.
+ *
+ * Not every output is an identifier: `1 2 3` cleans to `1_2_3`, which no store
+ * will quote. That is not this function's business to fix — a suggestion is
+ * `toPhysicalName` in an adapter, and a refusal is `assertSafeIdentifier` on the
+ * result.
+ */
+function physicalColumn(propertyName) {
+    return propertyName
+        .replace(/[^A-Za-z0-9_]/g, '_')
+        .replace(/_+/g, '_')
+        .slice(0, 60);
+}
+/**
+ * The column name a store exposes a property under, in the committed view and
+ * in the SELECT list of a read.
+ *
+ * **Why this is not simply the property's name.** It used to be. Every store
+ * wrote `\`Asset_Id\` AS \`Asset Id\`` — the physical column reached by cleaning,
+ * the alias taken verbatim — and the alias went through `ident`, which refuses
+ * rather than escapes. So a property could only be named something that was
+ * already a SQL identifier, which meant a source column genuinely called `Asset
+ * Id` could not be published under its own spelling.
+ *
+ * That mattered far more than it looks. A load matches a source's record to a
+ * property by property NAME — the store reads `row[property.name]` — so a
+ * publisher forced to rename the property to `Asset_Id`, keeping `Asset Id` in
+ * `columnName`, was publishing a type whose every read of that field returned
+ * `undefined`. `columnName` is lineage; nothing consults it on the write path.
+ * The loads committed, the row counts were right, and the column was NULL in
+ * every row. Thirteen types were loaded that way and six of them came out with
+ * most of their columns empty — 73 of 84 on the largest, across 313,833 rows.
+ * The verbatim alias is what forced the rename, so the alias is what changed.
+ *
+ * **Why the name is still kept when it is already an identifier.** The obvious
+ * fix — always alias to {@link physicalColumn} — would rename the output column
+ * of every existing view whose property name is not equal to its own cleaned
+ * form: a property called `Asset__Id` (two underscores collapse to one) or one
+ * 61 characters long (cut to 60). Those views work today and somebody is
+ * selecting from them by name. Renaming a column under a working consumer to
+ * tidy up an inconsistency is not a trade worth making, so the rule is the
+ * narrower one: **a name that SQL can take as it stands is kept exactly; only a
+ * name SQL cannot take is cleaned.** Every view that resolves today keeps every
+ * column name it has today.
+ *
+ * **This introduces no new way for two properties to collide.** If two distinct
+ * names produce one alias then they also produce one {@link physicalColumn}, so
+ * `assertNoColumnCollisions` already refuses the pair. Both unsafe: equal
+ * aliases *are* equal physical columns. Both safe: equal aliases are equal
+ * names, and there is only one property per name. One of each — a safe `x` and
+ * an unsafe `y` with `physicalColumn(y) === x` — means `x` contains no run of
+ * underscores and is at most 60 characters, so `physicalColumn(x) === x ===
+ * physicalColumn(y)` and the columns collide too.
+ */
+function outputAlias(propertyName) {
+    return isSafeIdentifier(propertyName) ? propertyName : physicalColumn(propertyName);
+}