uql-codemod 0.30.0 → 0.32.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
@@ -28,6 +28,7 @@ Only the `--flag=value` form is read, and anything unrecognised is an error: a m
 - 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.
 
@@ -38,6 +39,8 @@ 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`, `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.

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

@@ -16,13 +16,21 @@ const REMOVED_DECORATORS = new Map([
 ]);
 /**
  * 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.
+ * same reason as the decorators: what replaces each is decided at its call site.
  */
 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`'],
+    ['augmentWhere', 'spread the two maps: `{ ...where, ...extra }`'],
+    ['buildQueryWhereAsMap', 'a `$where` is a map already; name the key for ids: `{ id: [1, 2] }`'],
 ]);
+/** 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;
@@ -69,7 +77,7 @@ function propertyKey(name) {
  * 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) {
+function renameVirtualOption(decorator, node, ctx) {
     const options = decoratorOptions(decorator);
     const virtual = findProperty(options, 'virtual');
     if (!virtual) {
@@ -239,9 +247,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) {
@@ -249,7 +310,7 @@ function rewriteProperty(node, ctx) {
         }
         if (FIELD_DECORATORS.has(name)) {
             addFieldType(decorator, node, ctx);
-            renameVirtualOption(decorator, ctx, node);
+            renameVirtualOption(decorator, node, ctx);
         }
         if (RELATION_DECORATORS.has(name)) {
             addRelationEntity(decorator, node, ctx);
@@ -262,10 +323,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) {
@@ -274,40 +332,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
@@ -343,10 +393,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);
@@ -354,10 +404,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

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