uql-codemod 0.35.0 → 0.36.0

package/README.md

@@ -7,7 +7,7 @@
 
 # uql-codemod
 
-Rewrites [uql-orm](https://uql-orm.dev) entities across the breaking changes that can be made mechanically: the move from the legacy TypeScript decorators to the TC39 standard spec, and the renames and annotations that followed it. One command, on your own source, with a dry run first:
+Rewrites a [uql-orm](https://uql-orm.dev) project across the breaking changes that can be made mechanically. Dry run first:
 
 ```sh
 npx uql-codemod --dry-run
@@ -20,42 +20,42 @@ npx uql-codemod
 | `--dry-run`        | Report what would change and touch nothing.                                                                                                   |
 | `--include=<a,b>`  | Only files whose path contains one of these fragments.                                                                                        |
 
-Only the `--flag=value` form is read, and anything unrecognised is an error: a misspelled `--dry-run` would otherwise rewrite the project for real. It exits `0` when nothing is left for you, `1` when something is, and `2` when it could not start at all - a bad argument, or a project it cannot read.
+Only `--flag=value` is read, and anything unrecognised is an error. It exits `0` when nothing is left for you, `1` when something is, and `2` when it could not start. Edits are spliced into the text, so everything it does not touch stays byte for byte as written.
 
 ## What it rewrites
 
-- `@Field()` and `@Field({ ... })` with no `type`, and `@Id()`: inserts the `type` the property's declared TypeScript type implies. Skipped when `references` is present, because schema generation resolves that column from the referenced primary key.
-- Bare relation decorators: inserts `entity: () => X`, unwrapping arrays and the old `Relation<T>` alias.
-- `Relation<T>` becomes `T`, and its import goes with the last usage - `uql-orm` no longer exports it. A usage somewhere the codemod does not reach, such as a type alias, keeps the import and is reported.
-- `@Field({ virtual })` becomes `@Field({ computed })`, the name it was renamed to - written as a plain key, a quoted one, or a shorthand, which becomes `computed: virtual` so it keeps referring to the same local. A decorator given both names is reported instead, because which one wins is your call.
-- `mappedBy: 'author'` becomes the callback `(post) => post.author`, the one form left, named after the relation's target.
-- `@Index(['title', { column: 'createdAt', order: 'desc' }], { include: ['slug'] })` becomes `@Index((post) => [post.title, { column: post.createdAt, order: 'desc' }], { include: (post) => [post.slug] })`, and `references` pairs and the `@Entity`/`defineEntity`/`defineIndex`/`defineRelation` string forms likewise. A value that is not a literal is reported.
-- An aggregate's `$agg: { total: { $sum: 'amount' } }` becomes `$select: { total: { $sum: { amount: true } } }`, and `$text`'s `$fields: ['title']` becomes `$fields: { title: true }`.
-- `QueryWhereMap` and `RelationKeyMap`, renamed to `QueryWhere` and `KeyMap`, are renamed at their import and every use.
-- A primary key not called `id`, `_id` or `uuid`, and every composite key, gets the `[idKey]?: '...'` brand naming it, plus the import. `@Id` refuses a key it cannot name, since one that resolves to any column types `findOneById` against the wrong one.
-- `import 'reflect-metadata'` goes. Removing the package from your `package.json` is left to you.
-- `tsconfig.json`: removes `experimentalDecorators` and `emitDecoratorMetadata`, keeping the rest of the file - comments and formatting included - exactly as written.
-
-## What it refuses to do
-
-It reports rather than guesses, and exits non-zero when anything is left for you:
-
-- **`target: esnext`** is reported, not changed. Removing the line falls back to the compiler default (`es5` for `tsc`), and choosing a replacement means guessing which era the project targets. Any dated target works; `esnext` is the one where TypeScript emits decorator syntax untransformed.
-- **A value inherited through `extends`** cannot be edited here, so the base config is reported instead.
-- **`@Log()`, `@Serialized()`, `@Transactional()` and `@InjectQuerier()`** are reported and left in place. They no longer exist, and what to do instead is a judgement call - a `@Transactional()` method becomes a `pool.transaction(async (querier) => { ... })` around its body, and the codemod cannot know which pool.
-- **An export that no longer exists** (`setQuerierPool`, `getQuerier`, `augmentWhere`, `RelationMappedBy`, ...) is reported with what replaces it. A `$where` given an id, a list of them or a bare `raw()` needs no report: it is a compile error on that value, fixed by naming the key (`{ id: [1, 2] }`) or wrapping the raw in `$and`.
-- **A key written under a computed name** (`@Id() [KEY]?: string`) is reported: the brand has to spell the name out, and only you know what that expression evaluates to.
-- **Options it cannot read** (`@Field(sharedOptions)`, a spread, or a `@Field` never called at all) are left exactly as written. Replacing an argument it cannot parse would silently drop the options.
-- **A property whose type it cannot map to a column** (a `Json<T>`, a vector, a union that disagrees with itself) is reported as `needs a decision`. Those always had to declare `type` by hand anyway, because `design:type` reported the useless `Object`/`Array` for them.
-- **A branded string id**, e.g. ``type UUID = `${string}-${string}` ``, gets `type: String` plus a `worth a look` note. That is a real fork: `String` generates a text column, `'uuid'` a native one, and only you know which the database has.
+- `type` on a `@Field`/`@Id` that has none, from the property's declared type; not beside `references`, whose column comes from the key it points at.
+- `entity: () => X` on a bare relation decorator, and `Relation<T>` to `T`, its import going with the last use.
+- `virtual` to `computed` (on `@Field` and in `defineEntity`'s `fields`), a check's `expression` and a filter's `condition` to `where` (`@Entity`/`defineEntity`, `@Filter`, `defineFilter`), `raw('sql')` to the tagged template, and a `raw` alias argument onto `.as()`.
+- Members named by string to key-map callbacks: `mappedBy: 'author'` to `(post) => post.author`, and `@Index`, `include`, `references` and `@Entity`/`defineEntity`'s `indexes` and `hooks` likewise: `@Index((post) => [post.title])`.
+- An index expression to the callback an index takes, as an entry or a `column`: ``raw`lower("email")` `` to ``() => raw`lower("email")` ``, and a partial-index `where` string to `raw`, importing it; on entities and in the migration builder.
+- `col('cost')` to the ref it names, ``(product) => raw`${product.cost}` `` in a `computed` and `refs(Item).cost` in a statement, and `$lock: { wait: 'skip' }` to `{ $wait: 'skip' }`, or to `true` for `{}` and a `'block'` wait.
+- An aggregate's `$agg` to `$select`, and each field it or `$text`'s `$fields` names to a key: `{ $sum: { amount: true } }`.
+- Renamed exports, at the import and every use: `QueryWhereMap` to `QueryWhere`, `RelationKeyMap` to `KeyMap`, `FilterCondition` to `FilterWhere`, and the removed driver classes to the one each extended: `PgDialect`/`NeonDialect`/`PgliteDialect` to `PostgresDialect`, `CrdbQuerier`/`NeonQuerier` to `PgQuerier`, `LibsqlQuerier`/`TursoQuerier` to `HranaQuerier`, `MySql2Dialect` to `MySqlDialect`, `MongodbNativeDialect` to `MongoDialect`, moving the import to the entry that exports it.
+- The `[idKey]?: '...'` brand, and its import, on a key not called `id`, `_id` or `uuid` and on every composite.
+- `import 'reflect-metadata'`, and `experimentalDecorators`/`emitDecoratorMetadata` in `tsconfig.json`, comments and formatting kept.
+
+## What it leaves to you
+
+Reported with what to do, never guessed:
+
+- `target: esnext`, the one target that leaves decorators untransformed, and a value inherited through `extends`.
+- `@Log()`, `@Serialized()`, `@Transactional()` and `@InjectQuerier()`: a `@Transactional()` method becomes a `pool.transaction()` around its body, and only you know which pool.
+- An export removed with no one-to-one replacement (`setQuerierPool`, `getQuerier`, `augmentWhere`, `AbstractPgQuerier`, ...).
+- A value it cannot read: options passed as a variable or a spread, a list that is not a literal, a key under a computed name.
+- A partial-index `where` string that interpolates, since `raw` would bind what the template spliced in.
+- A `col()` whose entity it cannot tell: a raw built apart from its query, one under a relation filter, or a column no field maps.
+- SQL in a definition that names a column by hand, as a note: a rename reaches a callback's refs, ``(user) => raw`lower(${user.email})` ``, and never the text.
+- A property whose type maps to no column (`Json<T>`, a vector, a mixed union).
+- A branded string id, written as `type: String` to keep the column you have, with a note: `'uuid'` is a native column, and a migration.
 
 ## After it runs
 
-`tsc` is the rest of the migration, and that is the point: the annotations the codemod inserts are now _checked_ against the properties they describe, so anything it got wrong is a compile error rather than a silently wrong column. See the [upgrade guide](https://uql-orm.dev/upgrade-guide).
+`tsc` is the rest of the migration: what the codemod wrote is checked against the property it describes, so anything it got wrong is a compile error. See the [upgrade guide](https://uql-orm.dev/upgrade-guide).
 
 ## Why TypeScript 6
 
-TypeScript is a runtime dependency here: reading each property's type needs the checker. Version 6 is pinned because 7's `typescript` entry point exports no compiler API yet (it moved to `typescript/unstable/*`), and 7 has no standalone parser, which the `tsconfig.json` rewrite needs to keep your comments and formatting. A one-shot tool for a spec `uql-orm` no longer supports needs nothing newer; revisit once that API is stable.
+Reading each property's type needs the checker, so TypeScript is a runtime dependency. 7's entry point exports no compiler API yet and has no standalone parser, which the `tsconfig.json` rewrite needs to keep your formatting; revisit once that API is stable.
 
 ## License
 

package/dist/edits.d.ts

@@ -6,12 +6,13 @@ export type Edit = {
     readonly text: string;
 };
 /**
- * Applies edits back to front, so an earlier edit cannot shift the offsets of a later one.
- *
- * Replacing text rather than reprinting the file is what keeps the rest of it byte-for-byte: a codemod
- * that reformats everything it touches buries its own change in the diff.
+ * Applies edits back to front, so none shifts the offsets of another, and at a shared offset the replacement
+ * first, so an insertion there lands before it. Splicing rather than reprinting keeps the rest of the file
+ * byte for byte: a codemod that reformats everything it touches buries its own change in the diff.
  */
 export declare function applyEdits(text: string, edits: readonly Edit[]): string;
+export declare function replaced(node: ts.Node, text: string): Edit;
+export declare function inserted(node: ts.Node, text: string): Edit;
 /**
  * Removes one element of a comma-separated list - a parameter, a named import, a JSON property - taking
  * the separator that would otherwise dangle. The last element gives up the comma before it; any other

package/dist/edits.js

@@ -1,16 +1,21 @@
 /**
- * Applies edits back to front, so an earlier edit cannot shift the offsets of a later one.
- *
- * Replacing text rather than reprinting the file is what keeps the rest of it byte-for-byte: a codemod
- * that reformats everything it touches buries its own change in the diff.
+ * Applies edits back to front, so none shifts the offsets of another, and at a shared offset the replacement
+ * first, so an insertion there lands before it. Splicing rather than reprinting keeps the rest of the file
+ * byte for byte: a codemod that reformats everything it touches buries its own change in the diff.
  */
 export function applyEdits(text, edits) {
     let result = text;
-    for (const edit of [...edits].sort((a, b) => b.start - a.start)) {
+    for (const edit of [...edits].sort((a, b) => b.start - a.start || b.end - a.end)) {
         result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
     }
     return result;
 }
+export function replaced(node, text) {
+    return { start: node.getStart(), end: node.getEnd(), text };
+}
+export function inserted(node, text) {
+    return { start: node.getStart(), end: node.getStart(), text };
+}
 /**
  * Removes one element of a comma-separated list - a parameter, a named import, a JSON property - taking
  * the separator that would otherwise dangle. The last element gives up the comma before it; any other

package/dist/entitySql.d.ts

@@ -0,0 +1,23 @@
+import ts from 'typescript';
+import { type Edit } from './edits.js';
+/** `raw\`...\`` or `raw(...)`. */
+type RawSql = ts.TaggedTemplateExpression | ts.CallExpression;
+export declare function isRaw(node: ts.Node): node is RawSql;
+/**
+ * `() => ` before each expression a column list indexes, which an index takes as a callback now. One that
+ * interpolates takes the list callback's parameter as its refs: `(user) => [raw\`lower(${user.email})\`]`
+ * spliced in the key `'email'`, where the ref it reads now renders the column.
+ */
+export declare function expressionEntryEdits(list: ts.Expression | undefined): readonly Edit[];
+/** The expressions of a column list, written as one or returned by its callback: each entry or `column` that is `raw`. */
+export declare function columnExpressions(list: ts.Expression | undefined): readonly RawSql[];
+/** SQL text as a `raw` tagged template, escaping what would end or interpolate it. */
+export declare function rawTag(sql: string): string;
+/** A partial-index `where` string as `raw`, or nothing for a template that interpolates, whose values `raw` would bind. */
+export declare function rawWhereEdit(where: ts.Expression): Edit | undefined;
+/**
+ * The columns SQL names by hand, which a rename does not reach: each quoted identifier, and each bare word
+ * naming one of `members`. What a string literal holds is left out, as is a word called as a function.
+ */
+export declare function handNamedColumns(sql: ts.Expression, members: ReadonlySet<string>): readonly string[];
+export {};

package/dist/entitySql.js

@@ -0,0 +1,67 @@
+import ts from 'typescript';
+import { inserted, replaced } from './edits.js';
+import { propertyValue } from './keyMaps.js';
+export function isRaw(node) {
+    const callee = ts.isTaggedTemplateExpression(node)
+        ? node.tag
+        : ts.isCallExpression(node)
+            ? node.expression
+            : undefined;
+    return callee !== undefined && ts.isIdentifier(callee) && callee.text === 'raw';
+}
+/**
+ * `() => ` before each expression a column list indexes, which an index takes as a callback now. One that
+ * interpolates takes the list callback's parameter as its refs: `(user) => [raw\`lower(${user.email})\`]`
+ * spliced in the key `'email'`, where the ref it reads now renders the column.
+ */
+export function expressionEntryEdits(list) {
+    const param = list && ts.isArrowFunction(list) ? list.parameters[0]?.name : undefined;
+    const refs = param && ts.isIdentifier(param) ? param.text : '';
+    return columnExpressions(list).map((sql) => inserted(sql, `(${interpolates(sql) ? refs : ''}) => `));
+}
+/** The expressions of a column list, written as one or returned by its callback: each entry or `column` that is `raw`. */
+export function columnExpressions(list) {
+    const body = list && ts.isArrowFunction(list) ? list.body : list;
+    const entries = body && ts.isArrayLiteralExpression(body) ? body.elements : [];
+    return entries.flatMap((entry) => {
+        const sql = ts.isObjectLiteralExpression(entry) ? propertyValue(entry, 'column') : entry;
+        return sql && isRaw(sql) ? [sql] : [];
+    });
+}
+function interpolates(sql) {
+    return ts.isTaggedTemplateExpression(sql) && ts.isTemplateExpression(sql.template);
+}
+/** SQL text as a `raw` tagged template, escaping what would end or interpolate it. */
+export function rawTag(sql) {
+    return `raw\`${sql.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${')}\``;
+}
+/** A partial-index `where` string as `raw`, or nothing for a template that interpolates, whose values `raw` would bind. */
+export function rawWhereEdit(where) {
+    if (ts.isNoSubstitutionTemplateLiteral(where)) {
+        return inserted(where, 'raw');
+    }
+    return ts.isStringLiteral(where) ? replaced(where, rawTag(where.text)) : undefined;
+}
+/**
+ * The columns SQL names by hand, which a rename does not reach: each quoted identifier, and each bare word
+ * naming one of `members`. What a string literal holds is left out, as is a word called as a function.
+ */
+export function handNamedColumns(sql, members) {
+    const code = sqlText(sql)?.replace(/'(?:[^']|'')*'/g, "''") ?? '';
+    const quoted = Array.from(code.matchAll(/"[^"]+"|`[^`]+`/g), ([token]) => token.slice(1, -1));
+    const bare = Array.from(code.matchAll(/\b[A-Za-z_]\w*\b(?!\s*\()/g), ([word]) => word);
+    return [...new Set([...quoted, ...bare.filter((word) => members.has(word))])];
+}
+/** The text of a `raw` or a string, `?` standing in for each interpolation. */
+function sqlText(sql) {
+    if (!sql) {
+        return undefined;
+    }
+    if (isRaw(sql)) {
+        return sqlText(ts.isTaggedTemplateExpression(sql) ? sql.template : sql.arguments[0]);
+    }
+    if (ts.isTemplateExpression(sql)) {
+        return [sql.head, ...sql.templateSpans.map((span) => span.literal)].map((part) => part.text).join(' ? ');
+    }
+    return ts.isStringLiteralLike(sql) ? sql.text : undefined;
+}

package/dist/keyMaps.d.ts

@@ -1,25 +1,28 @@
 import ts from 'typescript';
-import type { Edit } from './edits.js';
+import { type Edit } from './edits.js';
+/** The edits of one rewrite, or `undefined` where the value it reads could not be read. */
+export type Edits = readonly Edit[] | undefined;
 /** A callback's parameter, named after the class it reads: `Post` -> `post`. */
 export declare function paramFor(className: string | undefined): string;
+/** `post.title`, or `post['first-name']` for a key that is no identifier. */
+export declare function memberAccess(param: string, key: string): string;
 /** A key's name where it is spelled out, which is every form but a computed one (`{ [k]: v }`). */
 export declare function propertyKey(name: ts.PropertyName): string | undefined;
 /** The initializer of the property `name` in an object literal, however its key is written. */
 export declare function propertyValue(node: ts.ObjectLiteralExpression, name: string): ts.Expression | undefined;
 /** `'amount'` or `['title', 'body']` -> `{ amount: true }`, the key map a statement names fields by. */
-export declare function fieldKeysEdit(value: ts.Expression): Edit | undefined;
+export declare function fieldKeysEdits(value: ts.Expression): Edits;
 /** Whether `value` is already a function, the form every rewrite here produces. */
 export declare function isCallback(value: ts.Expression): boolean;
 /** `['title', { column: 'createdAt' }]` -> `(post) => [post.title, { column: post.createdAt }]`. */
-export declare function keyListEdit(list: ts.Expression, param: string): Edit | undefined;
+export declare function keyListEdits(list: ts.Expression, param: string): Edits;
 /** `'author'` -> `(post) => post.author`, `param` being the relation's target. */
-export declare function mappedByEdit(value: ts.Expression, param: string): Edit | undefined;
+export declare function mappedByEdits(value: ts.Expression, param: string): Edits;
 /**
  * `[{ local: 'customerCode', foreign: 'code' }]` -> `(order, customer) => [{ local: order.customerCode,
  * foreign: customer.code }]`. A self-relation would give both parameters one name, so it reads
  * `(local, foreign)` instead.
  */
-export declare function referencesEdit(value: ts.Expression, owner: string, target: string): Edit | undefined;
+export declare function referencesEdits(value: ts.Expression, owner: string, target: string): Edits;
 /** The class an `entity: () => Post` getter returns, as written. */
 export declare function entityGetterTarget(relation: ts.ObjectLiteralExpression): string | undefined;
-export declare function replaced(node: ts.Node, text: string): Edit;

package/dist/keyMaps.js

@@ -1,4 +1,5 @@
 import ts from 'typescript';
+import { inserted, replaced } from './edits.js';
 /** A callback's parameter, named after the class it reads: `Post` -> `post`. */
 export function paramFor(className) {
     return className ? className[0].toLowerCase() + className.slice(1) : 'entity';
@@ -7,7 +8,7 @@ function isIdentifierName(key) {
     return /^[\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*$/u.test(key);
 }
 /** `post.title`, or `post['first-name']` for a key that is no identifier. */
-function memberAccess(param, key) {
+export function memberAccess(param, key) {
     return isIdentifierName(key) ? `${param}.${key}` : `${param}['${key}']`;
 }
 /** A key's name where it is spelled out, which is every form but a computed one (`{ [k]: v }`). */
@@ -20,93 +21,76 @@ export function propertyValue(node, name) {
     return property?.initializer;
 }
 /** `'amount'` or `['title', 'body']` -> `{ amount: true }`, the key map a statement names fields by. */
-export function fieldKeysEdit(value) {
+export function fieldKeysEdits(value) {
     const names = ts.isArrayLiteralExpression(value) ? value.elements : [value];
     if (!names.every((name) => ts.isStringLiteralLike(name))) {
         return undefined;
     }
     const keys = names.map(({ text }) => `${isIdentifierName(text) ? text : `'${text}'`}: true`);
-    return replaced(value, `{ ${keys.join(', ')} }`);
+    return [replaced(value, `{ ${keys.join(', ')} }`)];
 }
 /** Whether `value` is already a function, the form every rewrite here produces. */
 export function isCallback(value) {
     return ts.isArrowFunction(value) || ts.isFunctionExpression(value);
 }
 /** `['title', { column: 'createdAt' }]` -> `(post) => [post.title, { column: post.createdAt }]`. */
-export function keyListEdit(list, param) {
-    const text = ts.isArrayLiteralExpression(list)
-        ? spliced(list, list.elements.map((entry) => [entry, keyListEntry(entry, param)]))
+export function keyListEdits(list, param) {
+    return ts.isArrayLiteralExpression(list)
+        ? callbackEdits(list, param, list.elements.map((entry) => keyListEntryEdits(entry, param)))
         : undefined;
-    return callbackEdit(list, param, text);
 }
 /** `'author'` -> `(post) => post.author`, `param` being the relation's target. */
-export function mappedByEdit(value, param) {
-    return callbackEdit(value, param, ts.isStringLiteralLike(value) ? memberAccess(param, value.text) : undefined);
+export function mappedByEdits(value, param) {
+    return ts.isStringLiteralLike(value)
+        ? [replaced(value, `(${param}) => ${memberAccess(param, value.text)}`)]
+        : undefined;
 }
 /**
  * `[{ local: 'customerCode', foreign: 'code' }]` -> `(order, customer) => [{ local: order.customerCode,
  * foreign: customer.code }]`. A self-relation would give both parameters one name, so it reads
  * `(local, foreign)` instead.
  */
-export function referencesEdit(value, owner, target) {
+export function referencesEdits(value, owner, target) {
     const [local, foreign] = owner === target ? ['local', 'foreign'] : [owner, target];
-    const text = ts.isArrayLiteralExpression(value)
-        ? spliced(value, value.elements.map((pair) => [pair, referenceText(pair, local, foreign)]))
+    return ts.isArrayLiteralExpression(value)
+        ? callbackEdits(value, `${local}, ${foreign}`, value.elements.map((pair) => referenceEdits(pair, local, foreign)))
         : undefined;
-    return callbackEdit(value, `${local}, ${foreign}`, text);
 }
 /** The class an `entity: () => Post` getter returns, as written. */
 export function entityGetterTarget(relation) {
     const getter = propertyValue(relation, 'entity');
     return getter && ts.isArrowFunction(getter) && ts.isIdentifier(getter.body) ? getter.body.text : undefined;
 }
-/** An expression entry (`raw\`...\``) and a `column` that is not a string stay as written. */
-function keyListEntry(entry, param) {
+/** A column-list entry, its name read off the key map: an expression, or a `column` given otherwise, has none. */
+function keyListEntryEdits(entry, param) {
     if (ts.isStringLiteralLike(entry)) {
-        return memberAccess(param, entry.text);
+        return [replaced(entry, memberAccess(param, entry.text))];
     }
     if (ts.isTaggedTemplateExpression(entry) || ts.isCallExpression(entry)) {
-        return entry.getText();
+        return [];
     }
     if (!ts.isObjectLiteralExpression(entry)) {
         return undefined;
     }
     const column = propertyValue(entry, 'column');
-    return column && ts.isStringLiteralLike(column)
-        ? spliced(entry, [[column, memberAccess(param, column.text)]])
-        : entry.getText();
+    return column && ts.isStringLiteralLike(column) ? [replaced(column, memberAccess(param, column.text))] : [];
 }
-function referenceText(pair, local, foreign) {
+function referenceEdits(pair, local, foreign) {
     if (!ts.isObjectLiteralExpression(pair)) {
         return undefined;
     }
     const localKey = propertyValue(pair, 'local');
     const foreignKey = propertyValue(pair, 'foreign');
     return localKey && foreignKey && ts.isStringLiteralLike(localKey) && ts.isStringLiteralLike(foreignKey)
-        ? spliced(pair, [
-            [localKey, memberAccess(local, localKey.text)],
-            [foreignKey, memberAccess(foreign, foreignKey.text)],
-        ])
+        ? [
+            replaced(localKey, memberAccess(local, localKey.text)),
+            replaced(foreignKey, memberAccess(foreign, foreignKey.text)),
+        ]
         : undefined;
 }
-/** `node`'s text with each part swapped for its own, everything between kept as written. */
-function spliced(node, parts) {
-    if (!parts.every((part) => part[1] !== undefined)) {
-        return undefined;
-    }
-    const start = node.getStart();
-    const source = node.getText();
-    const sorted = [...parts].sort(([a], [b]) => a.getStart() - b.getStart());
-    const { text, at } = sorted.reduce((acc, [part, replacement]) => ({
-        text: acc.text + source.slice(acc.at, part.getStart() - start) + replacement,
-        at: part.getEnd() - start,
-    }), { text: '', at: 0 });
-    return text + source.slice(at);
-}
-/** `value` replaced by `(params) => body`, or nothing when the body could not be read. */
-function callbackEdit(value, params, body) {
-    return body === undefined ? undefined : replaced(value, `(${params}) => ${body}`);
-}
-export function replaced(node, text) {
-    return { start: node.getStart(), end: node.getEnd(), text };
+/** `(params) => ` before `body`, with the edits of its parts, or nothing where one could not be read. */
+function callbackEdits(body, params, parts) {
+    return parts.every((part) => part !== undefined)
+        ? [inserted(body, `(${params}) => `), ...parts.flat()]
+        : undefined;
 }

package/dist/transform.js

@@ -1,7 +1,8 @@
 import ts from 'typescript';
-import { applyEdits, removeFromList } from './edits.js';
+import { applyEdits, inserted, removeFromList, replaced } from './edits.js';
+import { columnExpressions, expressionEntryEdits, handNamedColumns, isRaw, rawTag, rawWhereEdit } from './entitySql.js';
 import { fieldTypeFor, isBrandedString, relationTargetFor } from './fieldType.js';
-import { entityGetterTarget, fieldKeysEdit, isCallback, keyListEdit, mappedByEdit, paramFor, propertyKey, propertyValue, referencesEdit, replaced, } from './keyMaps.js';
+import { entityGetterTarget, fieldKeysEdits, isCallback, keyListEdits, mappedByEdits, memberAccess, paramFor, propertyKey, propertyValue, referencesEdits, } from './keyMaps.js';
 const FIELD_DECORATORS = new Set(['Field', 'Id']);
 const RELATION_DECORATORS = new Set(['OneToOne', 'ManyToOne', 'OneToMany', 'ManyToMany']);
 /**
@@ -29,21 +30,25 @@ const REMOVED_EXPORTS = new Map([
     ['RelationKeyMapper', 'it is `(keys: KeyMap<E>) => Key<E>` now'],
     ['augmentWhere', 'spread the two maps: `{ ...where, ...extra }`'],
     ['buildQueryWhereAsMap', 'a `$where` is a map already; name the key for ids: `{ id: [1, 2] }`'],
-    ['PgDialect', 'the pools build `PostgresDialect` (`uql-orm/postgres`); name that where a dialect is typed'],
-    ['NeonDialect', 'the pools build `PostgresDialect` (`uql-orm/postgres`); name that where a dialect is typed'],
-    ['PgliteDialect', 'the pools build `PostgresDialect` (`uql-orm/postgres`); name that where a dialect is typed'],
-    ['MySql2Dialect', 'the pool builds `MySqlDialect` (`uql-orm/mysql`)'],
-    ['MongodbNativeDialect', 'the pool builds `MongoDialect` (`uql-orm/mongo`)'],
     ['AbstractPgQuerier', 'every pg-compatible pool returns `PgQuerier` (`uql-orm/postgres`), which is concrete'],
-    ['CrdbQuerier', 'every pg-compatible pool returns `PgQuerier` (`uql-orm/postgres`)'],
-    ['NeonQuerier', 'every pg-compatible pool returns `PgQuerier` (`uql-orm/postgres`)'],
-    ['LibsqlQuerier', 'the libSQL and Turso pools return `HranaQuerier` (`uql-orm/sqlite`)'],
-    ['TursoQuerier', 'the libSQL and Turso pools return `HranaQuerier` (`uql-orm/sqlite`)'],
 ]);
-/** Exports renamed and nothing else, so the import and every use of it in the file follow. */
+/**
+ * Exports renamed and nothing else - the driver classes were empty subclasses - so the import and every
+ * use follow, the import moving to `from` where the new name lives in another entry.
+ */
 const RENAMED_EXPORTS = new Map([
-    ['QueryWhereMap', 'QueryWhere'],
-    ['RelationKeyMap', 'KeyMap'],
+    ['QueryWhereMap', { to: 'QueryWhere' }],
+    ['RelationKeyMap', { to: 'KeyMap' }],
+    ['FilterCondition', { to: 'FilterWhere' }],
+    ['PgDialect', { to: 'PostgresDialect', from: 'uql-orm/postgres' }],
+    ['NeonDialect', { to: 'PostgresDialect', from: 'uql-orm/postgres' }],
+    ['PgliteDialect', { to: 'PostgresDialect', from: 'uql-orm/postgres' }],
+    ['CrdbQuerier', { to: 'PgQuerier', from: 'uql-orm/postgres' }],
+    ['NeonQuerier', { to: 'PgQuerier', from: 'uql-orm/postgres' }],
+    ['MySql2Dialect', { to: 'MySqlDialect', from: 'uql-orm/mysql' }],
+    ['MongodbNativeDialect', { to: 'MongoDialect', from: 'uql-orm/mongo' }],
+    ['LibsqlQuerier', { to: 'HranaQuerier', from: 'uql-orm/sqlite' }],
+    ['TursoQuerier', { to: 'HranaQuerier', from: 'uql-orm/sqlite' }],
 ]);
 /** A node's decorators, or none where it is a kind that cannot carry them. */
 function decoratorsOf(node) {
@@ -61,18 +66,19 @@ function decoratorOptions(node) {
         return { kind: 'opaque', reason: 'it is used without being called' };
     }
     const [first] = node.expression.arguments;
-    if (!first) {
-        return { kind: 'empty', call: node.expression };
-    }
-    if (!ts.isObjectLiteralExpression(first)) {
-        return { kind: 'opaque', reason: `its options are passed as '${first.getText()}'` };
+    return first ? optionsOf(first) : { kind: 'empty', call: node.expression };
+}
+/** The options `value` writes: a literal to read and write into, or why it is not one. */
+function optionsOf(value) {
+    if (!ts.isObjectLiteralExpression(value)) {
+        return { kind: 'opaque', reason: `its options are passed as '${value.getText()}'` };
     }
-    return first.properties.some(ts.isSpreadAssignment)
+    return value.properties.some(ts.isSpreadAssignment)
         ? { kind: 'opaque', reason: 'its options object spreads another' }
-        : { kind: 'literal', node: first };
+        : { kind: 'literal', node: value };
 }
 /**
- * The property `name` in the decorator's options, whether its key is plain, quoted or a shorthand.
+ * The property `name` in the options, whether its key is plain, quoted or a shorthand.
  *
  * All three forms, because both callers care about the option being *there*: one to leave an option
  * alone that is already stated, the other to rename it. Matching only the plain key inserted a second
@@ -85,27 +91,44 @@ function findProperty(options, name) {
     return options.node.properties.find((prop) => (ts.isPropertyAssignment(prop) || ts.isShorthandPropertyAssignment(prop)) && propertyKey(prop.name) === name);
 }
 /**
- * Renames the `virtual` option to `computed`, the one it was renamed to.
- *
- * Only the key is replaced, so the expression, its formatting and any comment inside the options
- * object survive untouched. A shorthand has no value to keep, so it becomes `computed: virtual` -
- * renaming the key alone would rebind it to a local that does not exist.
+ * Renames the option `from` to `to`. Only the key is replaced, so the value, its formatting and any comment
+ * inside survive; a shorthand has no value to keep, so it becomes `to: from`, since renaming the key alone
+ * would rebind it to a local that does not exist.
  */
-function renameVirtualOption(decorator, node, ctx) {
-    const options = decoratorOptions(decorator);
-    const virtual = findProperty(options, 'virtual');
-    if (!virtual) {
-        if (options.kind === 'opaque' && /\bvirtual\b/.test(decorator.getText())) {
-            ctx.unresolved.push(`${ctx.describe(node)}: ${options.reason}`);
-        }
+function renameOption(options, from, to, node, ctx) {
+    const property = findProperty(options, from);
+    if (!property) {
         return;
     }
-    if (findProperty(options, 'computed')) {
-        ctx.unresolved.push(`${ctx.describe(node)}: gives both 'virtual' and 'computed'; keep 'computed'.`);
+    if (findProperty(options, to)) {
+        ctx.unresolved.push(`${ctx.describe(node)}: gives both '${from}' and '${to}'; keep '${to}'.`);
         return;
     }
-    const text = ts.isShorthandPropertyAssignment(virtual) ? 'computed: virtual' : 'computed';
-    ctx.edits.push({ start: virtual.name.getStart(), end: virtual.name.getEnd(), text });
+    ctx.edits.push(replaced(property.name, ts.isShorthandPropertyAssignment(property) ? `${to}: ${from}` : to));
+}
+/** {@link renameOption} for an option holding SQL - a field's `virtual`, a check's `expression` - noting that SQL. */
+function renameSqlOption(options, from, to, node, owner, ctx) {
+    renameOption(options, from, to, node, ctx);
+    if (options.kind === 'literal') {
+        noteHandNamedColumns(propertyValue(options.node, from) ?? propertyValue(options.node, to), owner, ctx);
+    }
+}
+/** Notes SQL that names a column by hand, which a rename does not reach. */
+function noteHandNamedColumns(sql, owner, ctx) {
+    const names = sql ? handNamedColumns(sql, memberNames(owner.entity, ctx.checker)) : [];
+    if (!sql || !names.length) {
+        return;
+    }
+    ctx.notes.push(`${ctx.describe(sql)}: SQL names ${names.map((name) => `'${name}'`).join(', ')} by hand, which a rename ` +
+        `does not reach; read each off a callback's refs instead: (${owner.param}) => raw\`...\${${owner.param}.<member>}...\``);
+}
+/** The names of the members of the entity `node` declares or names. */
+function memberNames(node, checker) {
+    const type = checker.getTypeAtLocation(node);
+    return propertyNames(type.getConstructSignatures()[0]?.getReturnType() ?? type);
+}
+function propertyNames(type) {
+    return new Set(type.getProperties().map(({ name }) => name));
 }
 /** Inserts `option` into the decorator's options object, creating one when the call has no arguments. */
 function insertOption(options, option) {
@@ -115,9 +138,7 @@ function insertOption(options, option) {
         return { start: args.pos, end: args.end, text: `{ ${option} }` };
     }
     const first = options.node.properties[0];
-    return first
-        ? { start: first.getStart(), end: first.getStart(), text: `${option}, ` }
-        : { start: options.node.getStart(), end: options.node.getEnd(), text: `{ ${option} }` };
+    return first ? inserted(first, `${option}, `) : replaced(options.node, `{ ${option} }`);
 }
 /**
  * Writes one option the decorator can no longer infer at runtime, or records why it could not.
@@ -174,7 +195,7 @@ function addRelationEntity(decorator, node, ctx) {
     });
 }
 /**
- * Writes the edit `rewrite` reads off `value`, which still names members as strings, or reports it
+ * Writes the edits `rewrite` reads off `value`, which still names members as strings, or reports it
  * where it could not be read: what it holds is only known at runtime. A callback or an object literal
  * is already the new form, and kept.
  */
@@ -182,23 +203,23 @@ function rewriteValue(value, rewrite, node, advice, ctx) {
     if (!value || isCallback(value) || ts.isObjectLiteralExpression(value)) {
         return;
     }
-    const edit = rewrite(value);
-    if (edit) {
-        ctx.edits.push(edit);
+    const edits = rewrite(value);
+    if (edits) {
+        ctx.edits.push(...edits);
     }
     else {
         ctx.unresolved.push(`${ctx.describe(node)}: ${advice}; this one could not be read`);
     }
 }
 function rewriteKeyList(value, param, node, what, ctx) {
-    rewriteValue(value, (list) => keyListEdit(list, param), node, `write ${what} as a key-map callback`, ctx);
+    rewriteValue(value, (list) => keyListEdits(list, param), node, `write ${what} as a key-map callback`, ctx);
 }
 /**
- * Rewrites what a class decorator names by string - `@Index` columns and `include`, and `@Entity`'s
- * `indexes`, `hooks` and `relations` - into key-map callbacks named after the class.
+ * Rewrites a class's decorators - `@Index`, `@Filter` and `@Entity`'s options - for what they define now:
+ * members named by string read off key maps named after the class, and SQL written as it is taken.
  */
 function rewriteClassDecorators(node, ctx) {
-    const param = paramFor(node.name?.text);
+    const owner = { param: paramFor(node.name?.text), entity: node };
     for (const decorator of decoratorsOf(node)) {
         if (!ts.isCallExpression(decorator.expression)) {
             continue;
@@ -206,54 +227,118 @@ function rewriteClassDecorators(node, ctx) {
         const [first, second] = decorator.expression.arguments;
         const name = decoratorName(decorator);
         if (name === 'Index') {
-            rewriteKeyList(first, param, decorator, "'@Index' columns", ctx);
-            if (second && ts.isObjectLiteralExpression(second)) {
-                rewriteKeyList(propertyValue(second, 'include'), param, decorator, "'include'", ctx);
-            }
+            rewriteIndex(first, second, owner, decorator, "'@Index' columns", ctx);
+        }
+        else if (name === 'Filter' && second) {
+            renameOption(optionsOf(second), 'condition', 'where', decorator, ctx);
         }
         else if (name === 'Entity' && first && ts.isObjectLiteralExpression(first)) {
-            rewriteEntityOptions(first, param, ctx);
+            rewriteEntityOptions(first, owner, ctx);
         }
     }
 }
 /**
- * Rewrites what the imperative API names by string - `defineEntity(Post, { indexes, hooks, relations })`,
- * `defineIndex(Post, { columns, include })` and `defineRelation(Post, 'tag', { mappedBy, references })` -
- * into key-map callbacks. Only uql's shapes, a class and a literal options object, are read.
+ * Rewrites the imperative API the same way: `defineEntity(Post, { ... })`, `defineIndex(Post, { columns })`,
+ * `defineRelation(Post, 'tag', { mappedBy, references })` and `defineFilter(Post, 'live', { condition })`.
+ * Only uql's shapes, a class and a literal options object, are read.
  */
 function rewriteDefineCall(call, ctx) {
     const name = ts.isIdentifier(call.expression) ? call.expression.text : undefined;
-    const [entity, second, third] = call.arguments;
-    const param = paramFor(entity && ts.isIdentifier(entity) ? entity.text : undefined);
+    const [entity = call, second, third] = call.arguments;
+    const owner = { param: paramFor(ts.isIdentifier(entity) ? entity.text : undefined), entity };
     if (name === 'defineEntity' && second && ts.isObjectLiteralExpression(second)) {
-        rewriteEntityOptions(second, param, ctx);
+        rewriteEntityOptions(second, owner, ctx);
     }
     else if (name === 'defineIndex' && second && ts.isObjectLiteralExpression(second)) {
-        rewriteIndexOptions(second, param, ctx);
+        rewriteIndexOptions(second, owner, ctx);
     }
     else if (name === 'defineRelation' && third && ts.isObjectLiteralExpression(third)) {
-        rewriteRelationOptions(third, param, ctx);
+        rewriteRelationOptions(third, owner.param, ctx);
+    }
+    else if (name === 'defineFilter' && third) {
+        renameOption(optionsOf(third), 'condition', 'where', call, ctx);
     }
 }
-function rewriteEntityOptions(options, param, ctx) {
-    const indexes = propertyValue(options, 'indexes');
-    for (const index of indexes && ts.isArrayLiteralExpression(indexes) ? indexes.elements : []) {
+function rewriteEntityOptions(options, owner, ctx) {
+    for (const index of arrayElements(propertyValue(options, 'indexes'))) {
         if (ts.isObjectLiteralExpression(index)) {
-            rewriteIndexOptions(index, param, ctx);
+            rewriteIndexOptions(index, owner, ctx);
         }
     }
+    for (const check of arrayElements(propertyValue(options, 'checks'))) {
+        renameSqlOption(optionsOf(check), 'expression', 'where', check, owner, ctx);
+    }
+    for (const field of objectProperties(propertyValue(options, 'fields'))) {
+        renameSqlOption(optionsOf(field.initializer), 'virtual', 'computed', field, owner, ctx);
+    }
+    for (const filter of objectProperties(propertyValue(options, 'filters'))) {
+        renameOption(optionsOf(filter.initializer), 'condition', 'where', filter, ctx);
+    }
     for (const hook of objectProperties(propertyValue(options, 'hooks'))) {
-        rewriteKeyList(hook.initializer, param, hook, 'a hook list', ctx);
+        rewriteKeyList(hook.initializer, owner.param, hook, 'a hook list', ctx);
     }
     for (const relation of objectProperties(propertyValue(options, 'relations'))) {
         if (ts.isObjectLiteralExpression(relation.initializer)) {
-            rewriteRelationOptions(relation.initializer, param, ctx);
+            rewriteRelationOptions(relation.initializer, owner.param, ctx);
         }
     }
 }
-function rewriteIndexOptions(index, param, ctx) {
-    rewriteKeyList(propertyValue(index, 'columns'), param, index, "'columns'", ctx);
-    rewriteKeyList(propertyValue(index, 'include'), param, index, "'include'", ctx);
+function rewriteIndexOptions(index, owner, ctx) {
+    rewriteIndex(propertyValue(index, 'columns'), index, owner, index, "'columns'", ctx);
+}
+/**
+ * An index, as `@Index(columns, options)` or a `defineIndex`/`indexes` entry holding both: its columns and
+ * `include` read off the key map, its SQL written as {@link rewriteIndexSql} writes it, and noted.
+ */
+function rewriteIndex(columns, options, owner, node, what, ctx) {
+    const literal = options && ts.isObjectLiteralExpression(options) ? options : undefined;
+    rewriteKeyList(columns, owner.param, node, what, ctx);
+    rewriteKeyList(literal && propertyValue(literal, 'include'), owner.param, node, "'include'", ctx);
+    rewriteIndexSql(columns, literal, ctx);
+    for (const sql of [...columnExpressions(columns), literal && propertyValue(literal, 'where')]) {
+        noteHandNamedColumns(sql, owner, ctx);
+    }
+}
+/**
+ * An index's SQL as an index takes it now, on an entity and in the migration builder alike: each expression
+ * a callback, and a `where` string `raw`. A string it cannot write as `raw` is reported.
+ */
+function rewriteIndexSql(columns, options, ctx) {
+    ctx.edits.push(...expressionEntryEdits(columns));
+    const where = options && propertyValue(options, 'where');
+    if (!where || !isStringTyped(ctx.checker.getTypeAtLocation(where))) {
+        return;
+    }
+    const edit = rawWhereEdit(where);
+    if (edit) {
+        ctx.edits.push(edit);
+        ctx.imports.set('raw', 'the raw`...`');
+    }
+    else {
+        ctx.unresolved.push(`${ctx.describe(where)}: write the partial-index 'where' as raw\`...\` or a predicate; this one could not be read`);
+    }
+}
+/** Whether every value `type` admits is a string. */
+function isStringTyped(type) {
+    return type.isUnion() ? type.types.every(isStringTyped) : Boolean(type.flags & ts.TypeFlags.StringLike);
+}
+/** The migration builder's index methods, each with the position of the columns it takes. */
+const BUILDER_INDEX_METHODS = new Map([
+    ['index', 0],
+    ['unique', 0],
+    ['addIndex', 0],
+    ['createIndex', 1],
+]);
+/** Rewrites the SQL of the migration builder's `t.index()`, `t.unique()`, `t.addIndex()` and `m.createIndex()`. */
+function rewriteBuilderCall(call, ctx) {
+    const at = ts.isPropertyAccessExpression(call.expression)
+        ? BUILDER_INDEX_METHODS.get(call.expression.name.text)
+        : undefined;
+    if (at === undefined) {
+        return;
+    }
+    const options = call.arguments[at + 1];
+    rewriteIndexSql(call.arguments[at], options && ts.isObjectLiteralExpression(options) ? options : undefined, ctx);
 }
 /**
  * `owner` is the declaring class's parameter and `target` the related one's, read off the `entity`
@@ -261,15 +346,15 @@ function rewriteIndexOptions(index, param, ctx) {
  */
 function rewriteRelationOptions(relation, owner, ctx, target = paramFor(entityGetterTarget(relation))) {
     const advice = (what) => `write '${what}' as a key-map callback`;
-    const mappedBy = (value) => mappedByEdit(value, target);
-    const references = (value) => referencesEdit(value, owner, target);
+    const mappedBy = (value) => mappedByEdits(value, target);
+    const references = (value) => referencesEdits(value, owner, target);
     rewriteValue(propertyValue(relation, 'mappedBy'), mappedBy, relation, advice('mappedBy'), ctx);
     rewriteValue(propertyValue(relation, 'references'), references, relation, advice('references'), ctx);
 }
 /**
- * Rewrites what a statement names by string into keys: an aggregate's `$agg: { total: { $sum: 'amount' } }`
- * into `$select: { total: { $sum: { amount: true } } }`, and `$text`'s `$fields: ['title']` into
- * `{ title: true }`. Both keys are uql's own, so they are read wherever a literal holds them.
+ * Rewrites a statement's keys: an aggregate's `$agg: { total: { $sum: 'amount' } }` into
+ * `$select: { total: { $sum: { amount: true } } }`, `$text`'s `$fields: ['title']` into `{ title: true }`, and
+ * `$lock`'s `wait` into `$wait`. Each key is uql's own, so it is read wherever a literal holds it.
  */
 function rewriteStatementKeys(node, ctx) {
     const key = propertyKey(node.name);
@@ -277,7 +362,21 @@ function rewriteStatementKeys(node, ctx) {
         rewriteAggregate(node, ctx);
     }
     else if (key === '$fields' && isTextSearch(node.parent)) {
-        rewriteValue(node.initializer, fieldKeysEdit, node, "write '$fields' as { field: true }", ctx);
+        rewriteValue(node.initializer, fieldKeysEdits, node, "write '$fields' as { field: true }", ctx);
+    }
+    else if (key === '$lock' && ts.isObjectLiteralExpression(node.initializer)) {
+        rewriteLock(node.initializer, ctx);
+    }
+}
+/** `{ wait: 'skip' }` as `{ $wait: 'skip' }`, and `{}` or a `'block'` wait as `true`, which waits. */
+function rewriteLock(lock, ctx) {
+    const wait = propertyValue(lock, 'wait');
+    const blocks = wait && ts.isStringLiteralLike(wait) && wait.text === 'block';
+    if (!lock.properties.length || (blocks && lock.properties.length === 1)) {
+        ctx.edits.push(replaced(lock, 'true'));
+    }
+    else {
+        renameOption(optionsOf(lock), 'wait', '$wait', lock, ctx);
     }
 }
 function isTextSearch(node) {
@@ -295,7 +394,7 @@ function rewriteAggregate(agg, ctx) {
         for (const op of objectProperties(fn.initializer)) {
             const isStar = ts.isStringLiteralLike(op.initializer) && op.initializer.text === '*';
             if (!isStar) {
-                rewriteValue(op.initializer, fieldKeysEdit, op, `write '${op.name.getText()}' as { field: true }`, ctx);
+                rewriteValue(op.initializer, fieldKeysEdits, op, `write '${op.name.getText()}' as { field: true }`, ctx);
             }
         }
     }
@@ -304,6 +403,10 @@ function rewriteAggregate(agg, ctx) {
 function objectProperties(node) {
     return node && ts.isObjectLiteralExpression(node) ? node.properties.filter(ts.isPropertyAssignment) : [];
 }
+/** The elements of an array literal, or none where `node` is not one. */
+function arrayElements(node) {
+    return node && ts.isArrayLiteralExpression(node) ? node.elements : [];
+}
 /**
  * Drops `declare` from a decorated field. A `declare` field emits nothing, so the standard spec has
  * nothing to decorate and rejects it ("Decorators are not valid here"). Legacy decorators tolerated it
@@ -334,7 +437,7 @@ function unwrapRelationAlias(node, ctx) {
         ts.isIdentifier(declared.typeName) &&
         declared.typeName.text === 'Relation' &&
         declared.typeArguments?.length === 1) {
-        ctx.edits.push({ start: declared.getStart(), end: declared.getEnd(), text: declared.typeArguments[0].getText() });
+        ctx.edits.push(replaced(declared, declared.typeArguments[0].getText()));
         ctx.relationAlias.unwrapped += 1;
     }
 }
@@ -365,11 +468,10 @@ function deadImportNames(source, ctx) {
     return new Set(seen > 0 && seen === unwrapped ? ['Relation'] : []);
 }
 /**
- * Removes `import 'reflect-metadata'`, since the polyfill only ever fed `design:type`, and any name
- * `uql-orm` no longer exports.
+ * Removes `import 'reflect-metadata'`, since the polyfill only ever fed `design:type`, and each `dead` name
+ * from the imports {@link renameExports} left as written, having left the dead names out of the rest.
  */
-function dropDeadImports(source, ctx) {
-    const dead = deadImportNames(source, ctx);
+function dropDeadImports(source, dead, rewritten, ctx) {
     for (const statement of source.statements) {
         if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
             continue;
@@ -379,7 +481,7 @@ function dropDeadImports(source, ctx) {
             continue;
         }
         const named = statement.importClause?.namedBindings;
-        if (!named || !ts.isNamedImports(named)) {
+        if (!named || !ts.isNamedImports(named) || rewritten.has(statement)) {
             continue;
         }
         const dropped = named.elements.filter((element) => dead.has(element.name.text));
@@ -408,63 +510,70 @@ function isIdKeyBrand(member) {
  * a subclass that replaces an inherited `id` needs the brand precisely because the inherited name
  * would otherwise be taken for the key.
  *
- * Reports whether one was written, since `idKey` is then a value the file has to import.
+ * One written makes `idKey` a value the file has to import, which is recorded for {@link addImports}.
  */
 function brandIdKey(node, ctx) {
     const ids = node.members.filter((m) => ts.isPropertyDeclaration(m) && decoratorsOf(m).some((d) => decoratorName(d) === 'Id'));
     if (!ids.length || node.members.some(isIdKeyBrand)) {
-        return false;
+        return;
     }
     const names = ids.map((m) => propertyKey(m.name)).filter((name) => name !== undefined);
     if (names.length !== ids.length) {
         ctx.unresolved.push(`${ctx.describe(node)}: a key written as a computed name; add the 'idKey' brand by hand`);
-        return false;
+        return;
     }
     if (names.length === 1 && CONVENTIONAL_ID_NAMES.has(names[0])) {
-        return false;
+        return;
     }
     const indent = ' '.repeat(node.getSourceFile().getLineAndCharacterOfPosition(ids[0].getStart()).character);
     const brand = names.map((name) => `'${name}'`).join(' | ');
     const start = node.members.pos;
     ctx.edits.push({ start, end: start, text: `\n${indent}[idKey]?: ${brand};` });
-    return true;
+    ctx.imports.set('idKey', 'the brand(s)');
 }
 /**
- * Imports `idKey` where a brand was written, into the file's own `uql-orm` import. Reported instead
+ * Imports what the rewrites wrote (`idKey`, `raw`) into the file's own `uql-orm` import. Reported instead
  * where there is none: the package may be imported under a path this codemod does not recognise.
  */
-function addIdKeyImport(source, ctx) {
-    const imported = uqlImports(source);
-    if (imported.some((element) => importedName(element) === 'idKey')) {
+function addImports(source, rewritten, ctx) {
+    const imported = new Set(uqlImports(source).map(importedName));
+    const missing = [...ctx.imports].filter(([name]) => !imported.has(name));
+    if (!missing.length) {
         return;
     }
-    const [anchor] = imported;
+    const anchor = uqlImportDeclarations(source).find(({ declaration }) => !rewritten.has(declaration))?.elements[0];
     if (!anchor) {
-        ctx.unresolved.push(`${source.fileName}: import 'idKey' from 'uql-orm' for the brand(s) written here`);
+        for (const [name, what] of missing) {
+            ctx.unresolved.push(`${source.fileName}: import '${name}' from 'uql-orm' for ${what} written here`);
+        }
         return;
     }
-    ctx.edits.push({ start: anchor.getStart(), end: anchor.getStart(), text: 'idKey, ' });
+    ctx.edits.push(inserted(anchor, missing.map(([name]) => `${name}, `).join('')));
 }
-/** Everything the standard spec needs written onto one decorated property. */
+/** Everything the standard spec needs written onto one decorated property, and the options renamed since. */
 function rewriteProperty(node, ctx) {
+    const owner = { param: paramFor(node.parent.name?.text), entity: node.parent };
     const decorators = decoratorsOf(node);
     for (const decorator of decorators) {
         const name = decoratorName(decorator);
         if (!name) {
             continue;
         }
+        const options = decoratorOptions(decorator);
         if (FIELD_DECORATORS.has(name)) {
             addFieldType(decorator, node, ctx);
-            renameVirtualOption(decorator, node, ctx);
+            // Options it cannot read may still hold `virtual`, so they are reported where they mention it.
+            if (options.kind === 'opaque' && /\bvirtual\b/.test(decorator.getText())) {
+                ctx.unresolved.push(`${ctx.describe(node)}: ${options.reason}`);
+            }
+            renameSqlOption(options, 'virtual', 'computed', node, owner, ctx);
         }
-        const options = decoratorOptions(decorator);
         if (RELATION_DECORATORS.has(name)) {
             addRelationEntity(decorator, node, ctx);
         }
         if (RELATION_DECORATORS.has(name) && options.kind === 'literal') {
-            const owner = ts.isClassLike(node.parent) ? node.parent.name?.text : undefined;
             const target = relationTargetFor(ctx.checker.getTypeAtLocation(node), ctx.checker);
-            rewriteRelationOptions(options.node, paramFor(owner), ctx, paramFor(target));
+            rewriteRelationOptions(options.node, owner.param, ctx, paramFor(target));
         }
     }
     if (decorators.length) {
@@ -493,24 +602,49 @@ function reportRemovedExports(source, ctx) {
     }
 }
 /**
- * Renames each import of a {@link RENAMED_EXPORTS} name and every use of it in the file. An aliased
- * import only changes the name it imports; one whose new name the file already imports is dropped.
+ * Rewrites each import naming a {@link RENAMED_EXPORTS} export, renaming every use of it: a name moving
+ * entries gets an import from its new one, and a name the file already imports is dropped, as is a `dead`
+ * one. Returns the rewritten imports, which nothing else may edit.
  */
-function renameExports(source, ctx) {
-    const imported = uqlImports(source);
-    for (const element of imported) {
-        const renamed = RENAMED_EXPORTS.get(importedName(element));
-        if (!renamed) {
+function renameExports(source, dead, ctx) {
+    const imports = uqlImportDeclarations(source, true);
+    const kept = imports.flatMap(({ elements }) => elements).filter((element) => !renamedTo(element));
+    const bound = new Set(kept.map((element) => element.name.text));
+    const rewritten = new Set();
+    for (const { declaration, entry, elements } of imports) {
+        if (!elements.some(renamedTo)) {
             continue;
         }
-        if (element.propertyName) {
-            ctx.edits.push(replaced(element.propertyName, renamed));
-            continue;
+        const byEntry = new Map([[entry, []]]);
+        for (const element of elements.filter(({ name }) => !dead.has(name.text))) {
+            const rename = renamedTo(element);
+            const local = element.propertyName || !rename ? element.name.text : rename.to;
+            if (rename && !element.propertyName) {
+                ctx.edits.push(...usesOf(source, element.name, ctx.checker).map((use) => replaced(use, rename.to)));
+            }
+            if (rename && bound.has(local)) {
+                continue;
+            }
+            bound.add(local);
+            const target = rename?.from ?? entry;
+            const text = rename
+                ? `${element.isTypeOnly ? 'type ' : ''}${rename.to}${element.propertyName ? ` as ${local}` : ''}`
+                : element.getText();
+            byEntry.set(target, [...(byEntry.get(target) ?? []), text]);
         }
-        ctx.edits.push(...usesOf(source, element.name, ctx.checker).map((use) => replaced(use, renamed)));
-        const duplicate = imported.some((other) => other.name.text === renamed);
-        ctx.edits.push(duplicate ? removeFromList(element.parent.elements, element, source) : replaced(element.name, renamed));
+        const typeOnly = declaration.importClause?.phaseModifier === ts.SyntaxKind.TypeKeyword;
+        const keyword = typeOnly ? 'import type' : 'import';
+        const quote = declaration.moduleSpecifier.getText()[0];
+        const statements = [...byEntry]
+            .filter(([, names]) => names.length)
+            .map(([from, names]) => `${keyword} { ${names.join(', ')} } from ${quote}${from}${quote};`);
+        ctx.edits.push(statements.length ? replaced(declaration, statements.join('\n')) : removeStatement(declaration));
+        rewritten.add(declaration);
     }
+    return rewritten;
+}
+function renamedTo(element) {
+    return RENAMED_EXPORTS.get(importedName(element));
 }
 /** Every identifier in the file bound to the same symbol as `name`, besides `name` itself. */
 function usesOf(source, name, checker) {
@@ -528,50 +662,187 @@ function usesOf(source, name, checker) {
     return uses;
 }
 /**
- * What the file imports from `uql-orm` by name, which is every import this codemod reads or writes.
- * `entries` adds the driver entries (`uql-orm/postgres`, ...), for reporting only: an import written
- * into one of those would land on an entry that may not export it.
+ * The file's named imports from `uql-orm`. `entries` adds the driver entries (`uql-orm/postgres`, ...),
+ * for what is read by name only: `idKey` written into one would land on an entry that may not export it.
  */
-function uqlImports(source, entries = false) {
-    return source.statements.flatMap((statement) => {
-        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+function uqlImportDeclarations(source, entries = false) {
+    return source.statements.flatMap((declaration) => {
+        if (!ts.isImportDeclaration(declaration) || !ts.isStringLiteral(declaration.moduleSpecifier)) {
             return [];
         }
-        const specifier = statement.moduleSpecifier.text;
-        if (specifier !== 'uql-orm' && !(entries && specifier.startsWith('uql-orm/'))) {
+        const entry = declaration.moduleSpecifier.text;
+        if (entry !== 'uql-orm' && !(entries && entry.startsWith('uql-orm/'))) {
             return [];
         }
-        const bindings = statement.importClause?.namedBindings;
-        return bindings && ts.isNamedImports(bindings) ? [...bindings.elements] : [];
+        const bindings = declaration.importClause?.namedBindings;
+        return bindings && ts.isNamedImports(bindings) ? [{ declaration, entry, elements: bindings.elements }] : [];
     });
 }
+function uqlImports(source, entries = false) {
+    return uqlImportDeclarations(source, entries).flatMap(({ elements }) => elements);
+}
 /** The name an import specifier brings in, which is the original one where it was renamed. */
 function importedName(element) {
     return (element.propertyName ?? element.name).text;
 }
 /**
- * Rewrites `raw('sql')` into the tagged template, and a second alias argument into `.as()`. Only a
- * string-literal first argument qualifies: the callback form is unchanged, and a computed string is
- * left alone because a template cannot be built from a value that is not known here.
+ * Rewrites `raw('sql')` into the tagged template, and a second alias argument into `.as()`, the callback
+ * form's included. A computed string is left alone: a template cannot be built from a value not known here.
  */
 function rewriteRawCall(node, ctx, source) {
     if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression) || node.expression.text !== 'raw') {
         return;
     }
     const [expression, alias] = node.arguments;
-    if (!expression || !ts.isStringLiteral(expression) || node.arguments.length > 2) {
+    if (!expression || node.arguments.length > 2) {
         return;
     }
     const suffix = alias ? `.as(${alias.getText(source)})` : '';
-    ctx.edits.push({
-        start: node.getStart(source),
-        end: node.getEnd(),
-        text: `raw\`${escapeForTemplate(expression.text)}\`${suffix}`,
-    });
+    if (ts.isStringLiteral(expression)) {
+        ctx.edits.push(replaced(node, `${rawTag(expression.text)}${suffix}`));
+    }
+    else if (alias) {
+        ctx.edits.push({ start: expression.getEnd(), end: node.getEnd(), text: `)${suffix}` });
+    }
 }
-/** A backtick or a `${` inside the old string literal would end or interpolate the template. */
-function escapeForTemplate(text) {
-    return text.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+/**
+ * Rewrites each `col('x')` into the ref it names - `product.x` in a `computed` callback, `refs(Item).x` in a
+ * statement - where the entity its SQL renders against, and a member named `x`, can be told from here. Every
+ * other use is reported. Returns `col` as a dead import once no use is left.
+ */
+function rewriteColumnRefs(source, ctx) {
+    const element = uqlImports(source).find((use) => importedName(use) === 'col');
+    if (!element) {
+        return [];
+    }
+    const computed = new Map();
+    const unread = [];
+    for (const use of usesOf(source, element.name, ctx.checker)) {
+        const call = ts.isCallExpression(use.parent) && use.parent.expression === use ? use.parent : undefined;
+        const sql = call && ts.findAncestor(call, isRaw);
+        const option = sql?.parent;
+        const owner = option && ts.isPropertyAssignment(option) && isComputedOption(option) ? computedOwner(option) : undefined;
+        const edit = call && !owner ? statementRefEdit(call, ctx) : undefined;
+        if (call && sql && ts.isTaggedTemplateExpression(sql) && owner) {
+            computed.set(sql, { owner, calls: [...(computed.get(sql)?.calls ?? []), call] });
+        }
+        else if (edit) {
+            ctx.edits.push(edit);
+            ctx.imports.set('refs', 'the refs(...)');
+        }
+        else {
+            unread.push(use);
+        }
+    }
+    for (const [sql, { owner, calls }] of computed) {
+        const edits = computedRefEdits(sql, calls, owner, ctx);
+        if (edits) {
+            ctx.edits.push(...edits);
+        }
+        else {
+            unread.push(...calls);
+        }
+    }
+    for (const node of unread.sort((a, b) => a.getStart() - b.getStart())) {
+        ctx.unresolved.push(`${ctx.describe(node)}: 'col' was removed; read the column off refs(Entity), which the codemod could not tell here`);
+    }
+    return unread.length ? [] : ['col'];
+}
+function isComputedOption(option) {
+    const key = propertyKey(option.name);
+    return key === 'computed' || key === 'virtual';
+}
+/** The entity a field's `computed` SQL is declared on: the decorated property's class, or `defineEntity`'s first argument. */
+function computedOwner(option) {
+    const holder = ts.findAncestor(option, (node) => ts.isPropertyDeclaration(node) ||
+        (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'defineEntity'));
+    if (holder && ts.isPropertyDeclaration(holder)) {
+        return { param: paramFor(holder.parent.name?.text), entity: holder.parent };
+    }
+    const [entity] = holder?.arguments ?? [];
+    return entity && { param: paramFor(ts.isIdentifier(entity) ? entity.text : undefined), entity };
+}
+/** `(product) => ` before a `computed` raw, and `product.x` for each `col('x')` in it, where every one names a member. */
+function computedRefEdits(sql, calls, owner, ctx) {
+    const members = memberNames(owner.entity, ctx.checker);
+    const names = calls.map((call) => columnMember(call, members));
+    if (mentions(sql, owner.param) || !names.every((name) => name !== undefined)) {
+        return undefined;
+    }
+    return [
+        inserted(sql, `(${owner.param}) => `),
+        ...calls.map((call, at) => replaced(call, memberAccess(owner.param, names[at]))),
+    ];
+}
+/** `refs(Item).x` for a `col('x')` in a statement, where the entity its SQL renders against can be told. */
+function statementRefEdit(call, ctx) {
+    const entity = statementEntity(call, ctx.checker);
+    const name = entity && columnMember(call, propertyNames(entity.type));
+    return entity && name !== undefined ? replaced(call, memberAccess(`refs(${entity.name})`, name)) : undefined;
+}
+/** The member a `col('x')` names, where its one argument is a literal naming one of `members`. */
+function columnMember(call, members) {
+    const [name] = call.arguments;
+    return call.arguments.length === 1 && ts.isStringLiteralLike(name) && members.has(name.text) ? name.text : undefined;
+}
+/** Whether `node` reads a binding named `name`, which a callback parameter of that name would shadow. */
+function mentions(node, name) {
+    if (ts.isIdentifier(node)) {
+        return node.text === name && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node);
+    }
+    return ts.forEachChild(node, (child) => mentions(child, name) || undefined) ?? false;
+}
+/**
+ * The entity a statement's SQL renders against at `node`: the one its query names, or a relation a `$populate`
+ * reads there. Nothing where a function or a relation filter in between opens a scope of its own.
+ */
+function statementEntity(node, checker) {
+    const path = [];
+    for (let at = node; at.parent; at = at.parent) {
+        const { parent } = at;
+        if (ts.isFunctionLike(parent)) {
+            return undefined;
+        }
+        if (ts.isPropertyAssignment(parent)) {
+            path.unshift(propertyKey(parent.name) ?? '');
+        }
+        const queried = ts.isCallExpression(parent) && parent.arguments.some((argument) => argument === at);
+        const entity = queried ? queriedEntity(parent, checker) : undefined;
+        if (entity) {
+            return entityAlong(entity, path, node, checker);
+        }
+    }
+    return undefined;
+}
+/** The entity a call queries: its first argument's class, or the `$entity` its query names. */
+function queriedEntity(call, checker) {
+    const [first] = call.arguments;
+    const entity = first && ts.isObjectLiteralExpression(first) ? propertyValue(first, '$entity') : first;
+    const instance = entity && checker.getTypeAtLocation(entity).getConstructSignatures()[0]?.getReturnType();
+    return entity && ts.isIdentifier(entity) && instance ? { name: entity.text, type: instance } : undefined;
+}
+/** `entity` followed along `path`: into each relation a `$populate` names, and nowhere a relation filter opens. */
+function entityAlong(entity, path, node, checker) {
+    let current = entity;
+    for (const [at, key] of path.entries()) {
+        const property = current.type.getProperty(key);
+        const related = property && relatedClass(property, node, checker);
+        if (!related) {
+            continue;
+        }
+        const inScope = checker.getSymbolsInScope(node, ts.SymbolFlags.Class).some(({ name }) => name === related.name);
+        if (path[at - 1] !== '$populate' || !inScope) {
+            return undefined;
+        }
+        current = { name: related.name, type: checker.getDeclaredTypeOfSymbol(related) };
+    }
+    return current;
+}
+/** The class a relation property points at, one or many, or nothing where the property holds no class. */
+function relatedClass(property, node, checker) {
+    const type = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(property, node));
+    const symbol = (checker.getIndexTypeOfType(type, ts.IndexKind.Number) ?? type).getSymbol();
+    return symbol && symbol.flags & ts.SymbolFlags.Class ? symbol : undefined;
 }
 /** Rewrites one source file for the standard decorator spec. */
 export function transformFile(source, checker) {
@@ -580,12 +851,14 @@ export function transformFile(source, checker) {
         edits: [],
         unresolved: [],
         notes: [],
+        imports: new Map(),
         relationAlias: { seen: 0, unwrapped: 0 },
         describe: (node) => `${source.fileName}:${lineOf(node) + 1}`,
     };
     const lineOf = (node) => source.getLineAndCharacterOfPosition(node.getStart()).line;
     const rewritesRaw = uqlImports(source).some((element) => importedName(element) === 'raw');
-    let branded = false;
+    // The builder's methods are known by name alone, so they are read only in a file that imports uql-orm.
+    const importsUql = uqlImportDeclarations(source, true).length > 0;
     const visit = (node) => {
         reportRemovedDecorators(node, ctx);
         countRelationAlias(node, ctx);
@@ -596,24 +869,26 @@ export function transformFile(source, checker) {
             rewriteProperty(node, ctx);
         }
         if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) {
-            branded = brandIdKey(node, ctx) || branded;
+            brandIdKey(node, ctx);
             rewriteClassDecorators(node, ctx);
         }
         if (ts.isCallExpression(node)) {
             rewriteDefineCall(node, ctx);
         }
+        if (importsUql && ts.isCallExpression(node)) {
+            rewriteBuilderCall(node, ctx);
+        }
         if (ts.isPropertyAssignment(node)) {
             rewriteStatementKeys(node, ctx);
         }
         ts.forEachChild(node, visit);
     };
     visit(source);
-    renameExports(source, ctx);
+    const dead = new Set([...deadImportNames(source, ctx), ...rewriteColumnRefs(source, ctx)]);
+    const rewritten = renameExports(source, dead, ctx);
     reportRemovedExports(source, ctx);
-    dropDeadImports(source, ctx);
-    if (branded) {
-        addIdKeyImport(source, ctx);
-    }
+    dropDeadImports(source, dead, rewritten, ctx);
+    addImports(source, rewritten, ctx);
     return {
         fileName: source.fileName,
         text: applyEdits(source.getFullText(), ctx.edits),

package/package.json

@@ -2,7 +2,7 @@
   "name": "uql-codemod",
   "description": "Upgrade uql-orm across versions that introduce breaking changes",
   "license": "MIT",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "type": "module",
   "engines": {
     "node": ">=24"