uql-codemod 0.26.0 → 0.30.0

package/README.md

@@ -14,11 +14,11 @@ npx uql-codemod --dry-run
 npx uql-codemod
 ```
 
-| Flag | |
-|---|---|
+| 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. |
+| `--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.
 
@@ -27,6 +27,7 @@ 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.
+- `@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.
 - `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.
 
@@ -39,11 +40,11 @@ It reports rather than guesses, and exits non-zero when anything is left for you
 - **`@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.
+- **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.
 
 ## 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, 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).
 
 ## Why TypeScript 6
 

package/dist/transform.js

@@ -14,6 +14,15 @@ const REMOVED_DECORATORS = new Map([
     ['Transactional', 'wrap the body in `pool.transaction(async (querier) => { ... })`'],
     ['InjectQuerier', 'take the querier from the enclosing `pool.transaction()` callback'],
 ]);
+/**
+ * Exports that no longer exist, mapped to what to do instead. Reported rather than rewritten, for the
+ * same reason as the decorators: which pool belongs at a given call site is a judgement call.
+ */
+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'],
+]);
 function decoratorName(node) {
     const call = ts.isCallExpression(node.expression) ? node.expression : undefined;
     const target = call?.expression ?? node.expression;
@@ -36,9 +45,45 @@ function decoratorOptions(node) {
         ? { kind: 'opaque', reason: 'its options object spreads another' }
         : { kind: 'literal', node: first };
 }
-function hasProperty(options, name) {
-    return (options.kind === 'literal' &&
-        options.node.properties.some((prop) => prop.name && ts.isIdentifier(prop.name) && prop.name.text === name));
+/**
+ * The property `name` in the decorator's 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
+ * `type` beside a quoted one, and left a shorthand `virtual` behind while reporting nothing.
+ */
+function findProperty(options, name) {
+    if (options.kind !== 'literal') {
+        return undefined;
+    }
+    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.
+ *
+ * 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.
+ */
+function renameVirtualOption(decorator, ctx, node) {
+    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}`);
+        }
+        return;
+    }
+    if (findProperty(options, 'computed')) {
+        ctx.unresolved.push(`${ctx.describe(node)}: gives both 'virtual' and 'computed'; keep 'computed'.`);
+        return;
+    }
+    const text = ts.isShorthandPropertyAssignment(virtual) ? 'computed: virtual' : 'computed';
+    ctx.edits.push({ start: virtual.name.getStart(), end: virtual.name.getEnd(), text });
 }
 /** Inserts `option` into the decorator's options object, creating one when the call has no arguments. */
 function insertOption(options, option) {
@@ -61,7 +106,7 @@ function insertOption(options, option) {
  */
 function addInferredOption(decorator, node, ctx, spec) {
     const options = decoratorOptions(decorator);
-    if (spec.satisfiedBy.some((name) => hasProperty(options, name))) {
+    if (spec.satisfiedBy.some((name) => findProperty(options, name))) {
         return undefined;
     }
     if (options.kind === 'opaque') {
@@ -204,6 +249,7 @@ function rewriteProperty(node, ctx) {
         }
         if (FIELD_DECORATORS.has(name)) {
             addFieldType(decorator, node, ctx);
+            renameVirtualOption(decorator, ctx, node);
         }
         if (RELATION_DECORATORS.has(name)) {
             addRelationEntity(decorator, node, ctx);
@@ -227,6 +273,65 @@ function reportRemovedDecorators(node, ctx) {
         }
     }
 }
+/** Names an export that no longer exists, where it is imported from the package. */
+function reportRemovedExports(node, ctx) {
+    if (!ts.isImportDeclaration(node) || !ts.isStringLiteral(node.moduleSpecifier)) {
+        return;
+    }
+    if (node.moduleSpecifier.text !== 'uql-orm') {
+        return;
+    }
+    const bindings = node.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) {
+        return;
+    }
+    for (const element of bindings.elements) {
+        const name = (element.propertyName ?? element.name).text;
+        const advice = REMOVED_EXPORTS.get(name);
+        if (advice) {
+            ctx.unresolved.push(`${ctx.describe(element)}: '${name}' was removed; ${advice}`);
+        }
+    }
+}
+/** Whether this file's `raw` is the ORM's, so another library's function of that name is left alone. */
+function importsRaw(source) {
+    return source.statements.some((statement) => {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+            return false;
+        }
+        if (statement.moduleSpecifier.text !== 'uql-orm') {
+            return false;
+        }
+        const bindings = statement.importClause?.namedBindings;
+        return (!!bindings &&
+            ts.isNamedImports(bindings) &&
+            bindings.elements.some((element) => (element.propertyName ?? element.name).text === 'raw'));
+    });
+}
+/**
+ * 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.
+ */
+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) {
+        return;
+    }
+    const suffix = alias ? `.as(${alias.getText(source)})` : '';
+    ctx.edits.push({
+        start: node.getStart(source),
+        end: node.getEnd(),
+        text: `raw\`${escapeForTemplate(expression.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 one source file for the standard decorator spec. */
 export function transformFile(source, checker) {
     const ctx = {
@@ -238,9 +343,14 @@ export function transformFile(source, checker) {
         describe: (node) => `${source.fileName}:${lineOf(node) + 1}`,
     };
     const lineOf = (node) => source.getLineAndCharacterOfPosition(node.getStart()).line;
+    const rewritesRaw = importsRaw(source);
     const visit = (node) => {
         reportRemovedDecorators(node, ctx);
+        reportRemovedExports(node, ctx);
         countRelationAlias(node, ctx);
+        if (rewritesRaw) {
+            rewriteRawCall(node, ctx, source);
+        }
         if (ts.isPropertyDeclaration(node)) {
             rewriteProperty(node, ctx);
         }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "uql-codemod",
-  "description": "Migrates uql-orm entities from legacy decorators to the TC39 standard spec",
+  "description": "Upgrade uql-orm across versions that introduce breaking changes",
   "license": "MIT",
-  "version": "0.26.0",
+  "version": "0.30.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -21,6 +21,7 @@
     "README.md"
   ],
   "scripts": {
+    "prepack": "bun run build",
     "build": "rimraf dist .tsconfig.tsbuildinfo && tsc -b tsconfig.build.json",
     "clean": "rimraf dist .tsconfig.tsbuildinfo"
   },