uql-codemod 0.24.1 → 0.25.0

package/README.md

@@ -27,7 +27,6 @@ Only the `--flag=value` form is read, and anything unrecognised is an error: a m
 - `@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.
-- `@Transactional()` methods: drops the `@InjectQuerier() querier?: Querier` parameter and rewrites the body to `currentQuerier()`.
 - `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.
 
@@ -37,7 +36,7 @@ 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()` and `@Serialized()`** are reported and left in place. They no longer exist, and what to do instead is a judgement call.
+- **`@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.
 - **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.

package/dist/transform.js

@@ -4,13 +4,16 @@ import { fieldTypeFor, isBrandedString, relationTargetFor } from './fieldType.js
 const FIELD_DECORATORS = new Set(['Field', 'Id']);
 const RELATION_DECORATORS = new Set(['OneToOne', 'ManyToOne', 'OneToMany', 'ManyToMany']);
 /**
- * Decorators that no longer exist, and that the codemod does not remove for you.
- *
- * A standard-spec decorator cannot preserve a generic method's signature, which is why these went. What
- * to do instead is a judgement call - inline the logging, drop the serialisation - so the usage is
- * reported and left in place. Removing only the import would swap a clear error for a puzzling one.
+ * Decorators that no longer exist, mapped to what to do instead. None is removed for you: what to put
+ * in its place is a judgement call, and removing only the import would swap a clear error for a
+ * puzzling one.
  */
-const REMOVED_DECORATORS = new Set(['Log', 'Serialized']);
+const REMOVED_DECORATORS = new Map([
+    ['Log', 'delete it and its import'],
+    ['Serialized', 'delete it and its import'],
+    ['Transactional', 'wrap the body in `pool.transaction(async (querier) => { ... })`'],
+    ['InjectQuerier', 'take the querier from the enclosing `pool.transaction()` callback'],
+]);
 function decoratorName(node) {
     const call = ts.isCallExpression(node.expression) ? node.expression : undefined;
     const target = call?.expression ?? node.expression;
@@ -143,36 +146,6 @@ function countRelationAlias(node, ctx) {
         ctx.relationAlias.seen += 1;
     }
 }
-/**
- * Rewrites an `@InjectQuerier()` parameter into a `currentQuerier()` call.
- *
- * The standard spec has no parameter decorators, so the querier travels through async-local storage and
- * is read inside the body. Only the plain shape is rewritten - a named parameter in a method with a body.
- * A default value or a destructured parameter is reported: the author was doing something the codemod
- * would have to guess at.
- */
-function rewriteInjectQuerier(method, ctx) {
-    for (const parameter of method.parameters) {
-        if (!ts.getDecorators(parameter)?.some((d) => decoratorName(d) === 'InjectQuerier')) {
-            continue;
-        }
-        if (!method.body || !ts.isIdentifier(parameter.name) || parameter.initializer) {
-            ctx.unresolved.push(`${ctx.describe(parameter)}: cannot rewrite this '@InjectQuerier()' parameter`);
-            continue;
-        }
-        ctx.edits.push(removeFromList(method.parameters, parameter, method.getSourceFile()));
-        // The querier is read at the top of the body, keeping the name the parameter had.
-        const body = method.body;
-        const first = body.statements[0];
-        const indent = first ? ' '.repeat(first.getStart() - body.getSourceFile().getLineStarts()[ctx.lineOf(first)]) : '';
-        ctx.edits.push({
-            start: body.getStart() + 1,
-            end: body.getStart() + 1,
-            text: `\n${indent}const ${parameter.name.text} = currentQuerier();`,
-        });
-        ctx.imports.add('currentQuerier');
-    }
-}
 /** Removes a statement together with the rest of its line, so nothing is left blank behind it. */
 function removeStatement(node) {
     const source = node.getSourceFile();
@@ -181,44 +154,29 @@ function removeStatement(node) {
     return { start: node.getStart(), end: nextLineStart ?? node.getEnd(), text: '' };
 }
 /**
- * Brings the file's imports in line with what the rewrites left behind, in one pass:
- *
- * - `import 'reflect-metadata'` goes, since the polyfill only ever fed `design:type`.
- * - `InjectQuerier` goes with it, and its import would otherwise not compile: the standard spec has no
- *   parameter decorators, so `uql-orm` no longer exports one.
- * - whatever a rewrite needs (`currentQuerier`) is added, extending an existing `uql-orm` import rather
- *   than adding a second one.
- *
- * One function because all three edit the same statements, and doing them separately meant an import
- * could be dropped and re-added, or a name added to a statement another edit had already removed.
+ * Names `uql-orm` no longer exports and that the codemod does remove: only `Relation`, and only once
+ * every usage was unwrapped. A removed *decorator* keeps its import on purpose (see
+ * {@link REMOVED_DECORATORS}).
  */
-function reconcileImports(source, ctx) {
-    // Dropping runs first and hands over the `uql-orm` import it left standing: adding a name to a
-    // statement the other pass had already removed is the bug that made these one step to begin with.
-    addNeededImports(source, ctx, dropDeadImports(source, ctx));
-}
-/** Names `uql-orm` no longer exports. `Relation` joins them only when every usage was rewritten. */
 function deadImportNames(source, ctx) {
     const { seen, unwrapped } = ctx.relationAlias;
     if (seen > unwrapped) {
         ctx.unresolved.push(`${source.fileName}: ${seen - unwrapped} 'Relation<T>' reference(s) are somewhere this codemod does ` +
             'not rewrite; unwrap them and drop the import by hand');
     }
-    return new Set(seen > 0 && seen === unwrapped ? ['InjectQuerier', 'Relation'] : ['InjectQuerier']);
+    return new Set(seen > 0 && seen === unwrapped ? ['Relation'] : []);
 }
 /**
- * Removes `import 'reflect-metadata'` and any name that no longer exists, and returns the `uql-orm`
- * named imports still standing - `undefined` when there are none to extend.
+ * Removes `import 'reflect-metadata'`, since the polyfill only ever fed `design:type`, and any name
+ * `uql-orm` no longer exports.
  */
 function dropDeadImports(source, ctx) {
     const dead = deadImportNames(source, ctx);
-    let host;
     for (const statement of source.statements) {
         if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
             continue;
         }
-        const module = statement.moduleSpecifier.text;
-        if (module === 'reflect-metadata' && !statement.importClause) {
+        if (statement.moduleSpecifier.text === 'reflect-metadata' && !statement.importClause) {
             ctx.edits.push(removeStatement(statement));
             continue;
         }
@@ -234,25 +192,7 @@ function dropDeadImports(source, ctx) {
         for (const element of dropped) {
             ctx.edits.push(removeFromList(named.elements, element, source));
         }
-        if (module === 'uql-orm') {
-            host = named;
-        }
-    }
-    return host;
-}
-/** Adds what the rewrites need, extending `host` when there is one rather than adding a second import. */
-function addNeededImports(source, ctx, host) {
-    const missing = [...ctx.imports].filter((name) => !host?.elements.some((element) => element.name.text === name));
-    if (!missing.length) {
-        return;
     }
-    if (host) {
-        const last = host.elements[host.elements.length - 1];
-        ctx.edits.push({ start: last.getEnd(), end: last.getEnd(), text: `, ${missing.join(', ')}` });
-        return;
-    }
-    const position = source.statements[0]?.getStart() ?? 0;
-    ctx.edits.push({ start: position, end: position, text: `import { ${missing.join(', ')} } from 'uql-orm';\n` });
 }
 /** Everything the standard spec needs written onto one decorated property. */
 function rewriteProperty(node, ctx) {
@@ -281,8 +221,9 @@ function reportRemovedDecorators(node, ctx) {
     }
     for (const decorator of ts.getDecorators(node) ?? []) {
         const name = decoratorName(decorator);
-        if (name && REMOVED_DECORATORS.has(name)) {
-            ctx.unresolved.push(`${ctx.describe(decorator)}: '@${name}()' was removed; delete it and its import`);
+        const advice = name && REMOVED_DECORATORS.get(name);
+        if (advice) {
+            ctx.unresolved.push(`${ctx.describe(decorator)}: '@${name}()' was removed; ${advice}`);
         }
     }
 }
@@ -293,24 +234,20 @@ export function transformFile(source, checker) {
         edits: [],
         unresolved: [],
         notes: [],
-        imports: new Set(),
         relationAlias: { seen: 0, unwrapped: 0 },
-        describe: (node) => `${source.fileName}:${ctx.lineOf(node) + 1}`,
-        lineOf: (node) => source.getLineAndCharacterOfPosition(node.getStart()).line,
+        describe: (node) => `${source.fileName}:${lineOf(node) + 1}`,
     };
+    const lineOf = (node) => source.getLineAndCharacterOfPosition(node.getStart()).line;
     const visit = (node) => {
         reportRemovedDecorators(node, ctx);
         countRelationAlias(node, ctx);
         if (ts.isPropertyDeclaration(node)) {
             rewriteProperty(node, ctx);
         }
-        else if (ts.isMethodDeclaration(node)) {
-            rewriteInjectQuerier(node, ctx);
-        }
         ts.forEachChild(node, visit);
     };
     visit(source);
-    reconcileImports(source, ctx);
+    dropDeadImports(source, ctx);
     return {
         fileName: source.fileName,
         text: applyEdits(source.getFullText(), ctx.edits),

package/package.json

@@ -2,7 +2,7 @@
   "name": "uql-codemod",
   "description": "Migrates uql-orm entities from legacy decorators to the TC39 standard spec",
   "license": "MIT",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -35,9 +35,24 @@
   },
   "keywords": [
     "uql",
+    "uql-orm",
+    "orm",
     "codemod",
     "decorators",
-    "migration"
+    "tc39",
+    "migration",
+    "migrate",
+    "refactor",
+    "typescript",
+    "ts",
+    "javascript",
+    "database",
+    "sql",
+    "postgres",
+    "postgresql",
+    "mysql",
+    "sqlite",
+    "mongodb"
   ],
   "publishConfig": {
     "access": "public"