uql-codemod 0.28.0 → 0.31.0

package/README.md

@@ -7,7 +7,7 @@
 
 # uql-codemod
 
-Migrates [uql-orm](https://uql-orm.dev) entities from the legacy TypeScript decorators to the TC39 standard spec. One command, on your own source, with a dry run first:
+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:
 
 ```sh
 npx uql-codemod --dry-run
@@ -27,6 +27,8 @@ 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.
+- 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.
 
@@ -37,6 +39,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()`, `@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.
+- **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.

package/dist/index.js

@@ -42,14 +42,15 @@ export async function run({ project, dryRun, include }) {
     // The config is rewritten too: leaving `experimentalDecorators` on is what keeps a project compiling
     // against the old spec, so a codemod that only touched the sources would leave it half-migrated.
     const tsconfig = transformTsconfig(configPath, ts.sys.readFile(configPath) ?? '');
+    const rewritten = results.filter((r) => r.changed);
     if (!dryRun) {
-        await Promise.all(results.filter((r) => r.changed).map((r) => writeFile(r.fileName, r.text, 'utf8')));
+        await Promise.all(rewritten.map((r) => writeFile(r.fileName, r.text, 'utf8')));
         if (tsconfig.changed) {
             await writeFile(configPath, tsconfig.text, 'utf8');
         }
     }
     return {
-        changed: [...results.filter((r) => r.changed).map((r) => r.fileName), ...(tsconfig.changed ? [configPath] : [])],
+        changed: [...rewritten.map((r) => r.fileName), ...(tsconfig.changed ? [configPath] : [])],
         unresolved: [...results.flatMap((r) => r.unresolved), ...tsconfig.unresolved],
         notes: results.flatMap((r) => r.notes),
     };

package/dist/transform.js

@@ -23,6 +23,10 @@ const REMOVED_EXPORTS = new Map([
     ['getQuerierPool', 'take the pool from the module that builds it, or from Nest DI'],
     ['getQuerier', 'use `pool.withQuerier(...)` / `pool.transaction(...)`, which release the connection'],
 ]);
+/** A node's decorators, or none where it is a kind that cannot carry them. */
+function decoratorsOf(node) {
+    return ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : [];
+}
 function decoratorName(node) {
     const call = ts.isCallExpression(node.expression) ? node.expression : undefined;
     const target = call?.expression ?? node.expression;
@@ -45,9 +49,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, 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}`);
+        }
+        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) {
@@ -70,7 +110,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') {
@@ -203,9 +243,62 @@ function dropDeadImports(source, ctx) {
         }
     }
 }
+/** The names a key is read from without help, mirroring `NamedIdKey` in `uql-orm`. */
+const CONVENTIONAL_ID_NAMES = new Set(['id', '_id', 'uuid']);
+/** Whether the member is an `[idKey]?: ...` brand, matched by the name it is written under. */
+function isIdKeyBrand(member) {
+    return (ts.isPropertyDeclaration(member) &&
+        ts.isComputedPropertyName(member.name) &&
+        ts.isIdentifier(member.name.expression) &&
+        member.name.expression.text === 'idKey');
+}
+/**
+ * Names the class's key with the `idKey` brand, where a conventional name does not already.
+ *
+ * Only the class's own `@Id` properties are read, which is also what makes an overriding key right:
+ * 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.
+ */
+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;
+    }
+    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;
+    }
+    if (names.length === 1 && CONVENTIONAL_ID_NAMES.has(names[0])) {
+        return false;
+    }
+    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;
+}
+/**
+ * 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')) {
+        return;
+    }
+    const [anchor] = imported;
+    if (!anchor) {
+        ctx.unresolved.push(`${source.fileName}: import 'idKey' from 'uql-orm' for the brand(s) written here`);
+        return;
+    }
+    ctx.edits.push({ start: anchor.getStart(), end: anchor.getStart(), text: 'idKey, ' });
+}
 /** Everything the standard spec needs written onto one decorated property. */
 function rewriteProperty(node, ctx) {
-    const decorators = ts.canHaveDecorators(node) ? (ts.getDecorators(node) ?? []) : [];
+    const decorators = decoratorsOf(node);
     for (const decorator of decorators) {
         const name = decoratorName(decorator);
         if (!name) {
@@ -213,6 +306,7 @@ function rewriteProperty(node, ctx) {
         }
         if (FIELD_DECORATORS.has(name)) {
             addFieldType(decorator, node, ctx);
+            renameVirtualOption(decorator, node, ctx);
         }
         if (RELATION_DECORATORS.has(name)) {
             addRelationEntity(decorator, node, ctx);
@@ -225,10 +319,7 @@ function rewriteProperty(node, ctx) {
 }
 /** Names a decorator that no longer exists, wherever it appears. */
 function reportRemovedDecorators(node, ctx) {
-    if (!ts.canHaveDecorators(node)) {
-        return;
-    }
-    for (const decorator of ts.getDecorators(node) ?? []) {
+    for (const decorator of decoratorsOf(node)) {
         const name = decoratorName(decorator);
         const advice = name && REMOVED_DECORATORS.get(name);
         if (advice) {
@@ -237,40 +328,32 @@ 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;
+function reportRemovedExports(source, ctx) {
+    for (const element of uqlImports(source)) {
+        const name = importedName(element);
         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) => {
+/** What the file imports from `uql-orm` by name, which is every import this codemod reads or writes. */
+function uqlImports(source) {
+    return source.statements.flatMap((statement) => {
         if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
-            return false;
+            return [];
         }
         if (statement.moduleSpecifier.text !== 'uql-orm') {
-            return false;
+            return [];
         }
         const bindings = statement.importClause?.namedBindings;
-        return (!!bindings &&
-            ts.isNamedImports(bindings) &&
-            bindings.elements.some((element) => (element.propertyName ?? element.name).text === 'raw'));
+        return bindings && ts.isNamedImports(bindings) ? [...bindings.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
@@ -306,10 +389,10 @@ 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 rewritesRaw = uqlImports(source).some((element) => importedName(element) === 'raw');
+    let branded = false;
     const visit = (node) => {
         reportRemovedDecorators(node, ctx);
-        reportRemovedExports(node, ctx);
         countRelationAlias(node, ctx);
         if (rewritesRaw) {
             rewriteRawCall(node, ctx, source);
@@ -317,10 +400,17 @@ export function transformFile(source, checker) {
         if (ts.isPropertyDeclaration(node)) {
             rewriteProperty(node, ctx);
         }
+        if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) {
+            branded = brandIdKey(node, ctx) || branded;
+        }
         ts.forEachChild(node, visit);
     };
     visit(source);
+    reportRemovedExports(source, ctx);
     dropDeadImports(source, ctx);
+    if (branded) {
+        addIdKeyImport(source, ctx);
+    }
     return {
         fileName: source.fileName,
         text: applyEdits(source.getFullText(), ctx.edits),

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.28.0",
+  "version": "0.31.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"
   },