uql-codemod 0.35.0 → 0.35.1

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,37 @@ 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`, 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 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 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/transform.js

@@ -29,21 +29,24 @@ 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' }],
+    ['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) {
@@ -433,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;
@@ -493,24 +495,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. 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) {
+    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) {
+            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,23 +555,25 @@ 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;
@@ -608,11 +637,11 @@ export function transformFile(source, checker) {
         ts.forEachChild(node, visit);
     };
     visit(source);
-    renameExports(source, ctx);
+    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.35.0",
+  "version": "0.35.1",
   "type": "module",
   "engines": {
     "node": ">=24"