uql-codemod 0.38.0 → 0.39.0

package/README.md

@@ -28,7 +28,7 @@ Only `--flag=value` is read, and anything unrecognised is an error. It exits `0`
 - `entity: () => X` on a bare relation decorator, and `Relation<T>` to `T`, its import going with the last use.
 - `virtual` to `computed` (on `@Field` and in `defineEntity`'s `fields`), a check's `expression` and a filter's `condition` to `where` (`@Entity`/`defineEntity`, `@Filter`, `defineFilter`), `raw('sql')` to the tagged template, and a `raw` alias argument onto `.as()`.
 - Members named by string to callbacks: `mappedBy: 'author'` to `(post) => post.author`, and `@Index`, `include`, `references` and `@Entity`/`defineEntity`'s `indexes` and `hooks` likewise: `@Index((post) => [post.title])`.
-- `references: (post) => post.authorId` on a to-one (`@ManyToOne`, `@OneToOne`, or `defineEntity`/`defineRelation`) whose entity declares or inherits `authorId`, which it used to join by name.
+- `references: (post) => post.authorId` on a to-one (`@ManyToOne`, `@OneToOne`, or `defineEntity`/`defineRelation`) that names no foreign key, declaring `@Field({ references: () => User }) authorId` first on a decorated class that has no such column, typed as the key it points at.
 - A partial-index `where` string to `raw`, importing it, on entities and in the migration builder.
 - `col('cost')` to the ref it names, ``(product) => raw`${product.cost}` `` in a `computed` and `refs(Item).cost` in a statement, and `$lock: { wait: 'skip' }` to `{ $wait: 'skip' }`, or to `true` for `{}` and a `'block'` wait.
 - An aggregate's `$agg` to `$select`, and each field it or `$text`'s `$fields` names to a key: `{ $sum: { amount: true } }`.
@@ -44,7 +44,8 @@ Reported with what to do, never guessed:
 - `@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 to-one onto a composite key whose columns the entity declares: pair each with its key in `references`, which the error at startup spells out.
+- A to-one onto a composite key: declare a column per key and pair each with it in `references`.
+- A to-one in `defineEntity`/`defineRelation` whose entity has no foreign key column: declare it with `defineField`.
 - A partial-index `where` string that interpolates, since `raw` would bind what the template spliced in.
 - A `col()` whose entity it cannot tell: a raw built apart from its query, one under a relation filter, or a column no field maps.
 - SQL in a definition that names a column by hand, as a note: a rename reaches a callback's refs, ``(user) => raw`lower(${user.email})` ``, and never the text.

package/dist/transform.js

@@ -228,21 +228,63 @@ function addRelationEntity(decorator, node, ctx) {
     });
 }
 /**
- * Names the foreign key a to-one found by name alone, `references: (post) => post.authorId` beside `author`,
- * where its entity declares or inherits that key: a declared key is no longer joined by its name.
+ * Names the foreign key a to-one found by name alone, `references: (post) => post.authorId` beside `author`.
+ * A key the entity neither declares nor inherits is declared first, on a decorated property, typed as the
+ * target's key; elsewhere it is reported.
  */
-function addForeignKeyReference(relation, key, owner, ctx) {
+function addForeignKeyReference(relation, key, owner, ctx, property) {
     const options = { kind: 'literal', node: relation };
     const cardinality = propertyValue(relation, 'cardinality');
     const toOne = !cardinality || (ts.isStringLiteralLike(cardinality) && TO_ONE_CARDINALITIES.has(cardinality.text));
     const joined = ['mappedBy', 'through', 'references'].some((option) => findProperty(options, option));
     const last = relation.properties.at(-1);
-    const column = `${key}Id`;
-    if (!key || !last || !toOne || joined || !memberNames(owner.entity, ctx.checker).has(column)) {
+    if (!key || !last || !toOne || joined) {
         return;
     }
+    const column = `${key}Id`;
+    if (!memberNames(owner.entity, ctx.checker).has(column)) {
+        if (!property) {
+            ctx.unresolved.push(`${ctx.describe(relation)}: declare the foreign key column '${column}' and name it in 'references'`);
+            return;
+        }
+        const declared = foreignKeyColumn(property, column, relation, ctx);
+        if (!declared) {
+            return;
+        }
+        ctx.edits.push(declared);
+    }
     ctx.edits.push(appended(last, `, references: (${owner.param}) => ${memberAccess(owner.param, column)}`));
 }
+/** `@Field({ references: () => Target }) <column>?: <key type>;` ahead of the relation, or why it cannot be written. */
+function foreignKeyColumn(property, column, relation, ctx) {
+    const { checker } = ctx;
+    const targetType = checker.getNonNullableType(checker.getTypeAtLocation(property));
+    const target = entityGetterTarget(relation) ?? relationTargetFor(targetType, checker);
+    const keys = targetType.getProperties().filter((member) => member.declarations?.some(isIdProperty));
+    const [soleKey] = keys;
+    if (!target || !soleKey || keys.length > 1) {
+        const advice = keys.length > 1
+            ? `'${target}' has a composite key: declare a column per key and pair each in 'references'`
+            : `declare the foreign key column '${column}' and name it in 'references'`;
+        ctx.unresolved.push(`${ctx.describe(property)}: ${advice}`);
+        return undefined;
+    }
+    const source = property.getSourceFile();
+    const indent = ' '.repeat(source.getLineAndCharacterOfPosition(property.getStart()).character);
+    ctx.imports.set('Field', 'the foreign key column');
+    return inserted(property, `@Field({ references: () => ${target} }) ${column}?: ${keyTypeSource(soleKey, property, ctx)};\n${indent}`);
+}
+/** The key's type as written where that is in scope, the same file, or as the checker spells it out. */
+function keyTypeSource(key, at, ctx) {
+    const written = key.declarations?.find(isIdProperty)?.type;
+    if (written && written.getSourceFile() === at.getSourceFile()) {
+        return written.getText();
+    }
+    return ctx.checker.typeToString(ctx.checker.getNonNullableType(ctx.checker.getTypeOfSymbolAtLocation(key, at)), at);
+}
+function isIdProperty(node) {
+    return ts.isPropertyDeclaration(node) && decoratorsOf(node).some((decorator) => decoratorName(decorator) === 'Id');
+}
 /**
  * Writes the edits `rewrite` reads off `value`, which still names members as strings, or reports it
  * where it could not be read: what it holds is only known at runtime. A callback or an object literal
@@ -626,7 +668,7 @@ function rewriteProperty(node, ctx) {
             rewriteRelationOptions(options.node, owner.param, ctx, paramFor(target));
         }
         if (TO_ONE_DECORATORS.has(name) && options.kind === 'literal') {
-            addForeignKeyReference(options.node, propertyKey(node.name), owner, ctx);
+            addForeignKeyReference(options.node, propertyKey(node.name), owner, ctx, node);
         }
     }
     if (decorators.length) {

package/package.json

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