uql-codemod 0.34.0 → 0.35.1

package/README.md

@@ -7,55 +7,50 @@
 
 # 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
 npx uql-codemod
 ```
 
-| Flag               |                                                                                                                                                                                                                                                       |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--project=<path>` | `tsconfig.json` to read, defaulting to `./tsconfig.json`. It is a real program and not a parser, because the codemod writes down the types `design:type` used to report at runtime, so a config that covers your entities is what makes the run work. |
-| `--dry-run`        | Report what would change and touch nothing.                                                                                                                                                                                                           |
-| `--include=<a,b>`  | Only files whose path contains one of these fragments.                                                                                                                                                                                                |
+| Flag               |                                                                                                                                               |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--project=<path>` | The `tsconfig.json` to read, `./tsconfig.json` by default. It has to cover your entities: the type checker is what says each property's type. |
+| `--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.
-- 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.
+- `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`, and `raw('sql')` to the tagged template.
+- 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 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`, 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 refuses to do
+## What it leaves to you
 
-It reports rather than guesses, and exits non-zero when anything is left for you:
+Reported with what to do, never guessed:
 
-- **`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`, `QueryWhereMap`, `augmentWhere`, ...) 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'` generates a native one, and only you know which the database has.
+- `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 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 real dependency here, not a dev one: reading the types `design:type` used to report needs a checker, and that means shipping a compiler. Version 6 is pinned deliberately.
-
-TypeScript 7 is not a version bump away. Its `typescript` entry point exports only the version number, and the compiler API moved to `typescript/unstable/*` in a different shape. The gap that matters is the parser: 7 has no standalone one, and `ts.parseJsonText` is what lets the `tsconfig.json` rewrite keep your comments and formatting instead of reserialising the file.
-
-Staying on 6 costs nothing. This is a one-shot tool for a spec `uql-orm` no longer supports, so it never needs a new language feature, and 7 reads `experimentalDecorators` projects perfectly well when the time comes. Worth revisiting once that API drops the `unstable/` prefix and regains a parser.
+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/keyMaps.d.ts

@@ -0,0 +1,25 @@
+import ts from 'typescript';
+import type { Edit } from './edits.js';
+/** A callback's parameter, named after the class it reads: `Post` -> `post`. */
+export declare function paramFor(className: string | undefined): 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;
+/** 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;
+/** `'author'` -> `(post) => post.author`, `param` being the relation's target. */
+export declare function mappedByEdit(value: ts.Expression, param: string): Edit | 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 declare function referencesEdit(value: ts.Expression, owner: string, target: string): Edit | undefined;
+/** 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

@@ -0,0 +1,112 @@
+import ts from 'typescript';
+/** 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';
+}
+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) {
+    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 }`). */
+export function propertyKey(name) {
+    return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
+}
+/** The initializer of the property `name` in an object literal, however its key is written. */
+export function propertyValue(node, name) {
+    const property = node.properties.find((prop) => ts.isPropertyAssignment(prop) && propertyKey(prop.name) === name);
+    return property?.initializer;
+}
+/** `'amount'` or `['title', 'body']` -> `{ amount: true }`, the key map a statement names fields by. */
+export function fieldKeysEdit(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(', ')} }`);
+}
+/** 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)]))
+        : 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);
+}
+/**
+ * `[{ 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) {
+    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)]))
+        : 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) {
+    if (ts.isStringLiteralLike(entry)) {
+        return memberAccess(param, entry.text);
+    }
+    if (ts.isTaggedTemplateExpression(entry) || ts.isCallExpression(entry)) {
+        return entry.getText();
+    }
+    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();
+}
+function referenceText(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)],
+        ])
+        : 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 };
+}

package/dist/transform.js

@@ -1,6 +1,7 @@
 import ts from 'typescript';
 import { applyEdits, removeFromList } from './edits.js';
 import { fieldTypeFor, isBrandedString, relationTargetFor } from './fieldType.js';
+import { entityGetterTarget, fieldKeysEdit, isCallback, keyListEdit, mappedByEdit, paramFor, propertyKey, propertyValue, referencesEdit, replaced, } from './keyMaps.js';
 const FIELD_DECORATORS = new Set(['Field', 'Id']);
 const RELATION_DECORATORS = new Set(['OneToOne', 'ManyToOne', 'OneToMany', 'ManyToMany']);
 /**
@@ -22,20 +23,30 @@ const REMOVED_EXPORTS = new Map([
     ['setQuerierPool', 'pass the pool where it is used: `createFetchHandler({ pool })`, `querierMiddleware({ pool })`'],
     ['getQuerierPool', 'take the pool from the module that builds it, or from Nest DI'],
     ['getQuerier', 'use `pool.withQuerier(...)` / `pool.transaction(...)`, which release the connection'],
-    ['QueryWhereMap', 'it is `QueryWhere` now'],
     ['QueryWhereFieldMap', 'use `QueryWhere`'],
+    ['QueryStreamProjected', 'use `QueryProjected`'],
+    ['RelationMappedBy', "a 'mappedBy' is `(keys: KeyMap<E>) => Key<E>` now"],
+    ['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 - 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', { to: 'QueryWhere' }],
+    ['RelationKeyMap', { to: 'KeyMap' }],
+    ['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) {
@@ -76,10 +87,6 @@ function findProperty(options, name) {
     }
     return options.node.properties.find((prop) => (ts.isPropertyAssignment(prop) || ts.isShorthandPropertyAssignment(prop)) && propertyKey(prop.name) === name);
 }
-/** A key's name where it is spelled out, which is every form but a computed one (`{ [k]: v }`). */
-function propertyKey(name) {
-    return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : undefined;
-}
 /**
  * Renames the `virtual` option to `computed`, the one it was renamed to.
  *
@@ -169,6 +176,137 @@ function addRelationEntity(decorator, node, ctx) {
         },
     });
 }
+/**
+ * Writes the edit `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.
+ */
+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);
+    }
+    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);
+}
+/**
+ * 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.
+ */
+function rewriteClassDecorators(node, ctx) {
+    const param = paramFor(node.name?.text);
+    for (const decorator of decoratorsOf(node)) {
+        if (!ts.isCallExpression(decorator.expression)) {
+            continue;
+        }
+        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);
+            }
+        }
+        else if (name === 'Entity' && first && ts.isObjectLiteralExpression(first)) {
+            rewriteEntityOptions(first, param, 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.
+ */
+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);
+    if (name === 'defineEntity' && second && ts.isObjectLiteralExpression(second)) {
+        rewriteEntityOptions(second, param, ctx);
+    }
+    else if (name === 'defineIndex' && second && ts.isObjectLiteralExpression(second)) {
+        rewriteIndexOptions(second, param, ctx);
+    }
+    else if (name === 'defineRelation' && third && ts.isObjectLiteralExpression(third)) {
+        rewriteRelationOptions(third, param, ctx);
+    }
+}
+function rewriteEntityOptions(options, param, ctx) {
+    const indexes = propertyValue(options, 'indexes');
+    for (const index of indexes && ts.isArrayLiteralExpression(indexes) ? indexes.elements : []) {
+        if (ts.isObjectLiteralExpression(index)) {
+            rewriteIndexOptions(index, param, ctx);
+        }
+    }
+    for (const hook of objectProperties(propertyValue(options, 'hooks'))) {
+        rewriteKeyList(hook.initializer, param, hook, 'a hook list', ctx);
+    }
+    for (const relation of objectProperties(propertyValue(options, 'relations'))) {
+        if (ts.isObjectLiteralExpression(relation.initializer)) {
+            rewriteRelationOptions(relation.initializer, param, ctx);
+        }
+    }
+}
+function rewriteIndexOptions(index, param, ctx) {
+    rewriteKeyList(propertyValue(index, 'columns'), param, index, "'columns'", ctx);
+    rewriteKeyList(propertyValue(index, 'include'), param, index, "'include'", ctx);
+}
+/**
+ * `owner` is the declaring class's parameter and `target` the related one's, read off the `entity`
+ * getter unless the caller knows it from the property's type.
+ */
+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);
+    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.
+ */
+function rewriteStatementKeys(node, ctx) {
+    const key = propertyKey(node.name);
+    if (key === '$agg') {
+        rewriteAggregate(node, ctx);
+    }
+    else if (key === '$fields' && isTextSearch(node.parent)) {
+        rewriteValue(node.initializer, fieldKeysEdit, node, "write '$fields' as { field: true }", ctx);
+    }
+}
+function isTextSearch(node) {
+    return (ts.isObjectLiteralExpression(node) &&
+        ts.isPropertyAssignment(node.parent) &&
+        propertyKey(node.parent.name) === '$text');
+}
+function rewriteAggregate(agg, ctx) {
+    if (ts.isObjectLiteralExpression(agg.parent) && propertyValue(agg.parent, '$select')) {
+        ctx.unresolved.push(`${ctx.describe(agg)}: merge '$agg' into the '$select' beside it`);
+        return;
+    }
+    ctx.edits.push(replaced(agg.name, '$select'));
+    for (const fn of objectProperties(agg.initializer)) {
+        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);
+            }
+        }
+    }
+}
+/** The property assignments of an object literal, or none where `node` is not one. */
+function objectProperties(node) {
+    return node && ts.isObjectLiteralExpression(node) ? node.properties.filter(ts.isPropertyAssignment) : [];
+}
 /**
  * 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
@@ -298,12 +436,11 @@ function brandIdKey(node, ctx) {
  * Imports `idKey` where a brand was written, 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 addIdKeyImport(source, rewritten, ctx) {
+    if (uqlImports(source).some((element) => importedName(element) === 'idKey')) {
         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`);
         return;
@@ -322,9 +459,15 @@ function rewriteProperty(node, ctx) {
             addFieldType(decorator, node, ctx);
             renameVirtualOption(decorator, node, 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));
+        }
     }
     if (decorators.length) {
         dropDeclare(node, ctx);
@@ -352,23 +495,85 @@ function reportRemovedExports(source, ctx) {
     }
 }
 /**
- * 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.
+ * 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. Returns the
+ * rewritten imports, which nothing else may edit.
  */
-function uqlImports(source, entries = false) {
-    return source.statements.flatMap((statement) => {
-        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+function renameExports(source, 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;
+        }
+        const byEntry = new Map([[entry, []]]);
+        for (const element of elements) {
+            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]);
+        }
+        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) {
+    const symbol = checker.getSymbolAtLocation(name);
+    const uses = [];
+    const visit = (node) => {
+        if (ts.isIdentifier(node) && node !== name && node.text === name.text) {
+            if (symbol && checker.getSymbolAtLocation(node) === symbol) {
+                uses.push(node);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return uses;
+}
+/**
+ * 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 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;
@@ -421,14 +626,22 @@ export function transformFile(source, checker) {
         }
         if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) {
             branded = brandIdKey(node, ctx) || branded;
+            rewriteClassDecorators(node, ctx);
+        }
+        if (ts.isCallExpression(node)) {
+            rewriteDefineCall(node, ctx);
+        }
+        if (ts.isPropertyAssignment(node)) {
+            rewriteStatementKeys(node, ctx);
         }
         ts.forEachChild(node, visit);
     };
     visit(source);
+    const rewritten = renameExports(source, ctx);
     reportRemovedExports(source, ctx);
     dropDeadImports(source, ctx);
     if (branded) {
-        addIdKeyImport(source, ctx);
+        addIdKeyImport(source, rewritten, ctx);
     }
     return {
         fileName: source.fileName,

package/package.json

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