uql-codemod 0.49.0 → 0.50.1

package/README.md

@@ -25,13 +25,13 @@ Only `--flag=value` is read, and anything unrecognised is an error. It exits `0`
 ## What it rewrites
 
 - `virtual` to `computed` (on `@Field` and in `defineEntity`'s `fields`), a check's `expression` and a filter's `condition` to `where` (`@Entity`, `defineEntity`, `@Filter`), `raw('...')` to the `sql` tagged template, and a second argument onto `.as()`.
-- A column's options to its builder, last, after the rewrites above: `@Id()` and `@Field({ type: String, nullable: true, length: 80 })` to `@Field(f.number().id())` and `@Field(f.string().nullable().length(80))`, a NOT NULL column losing its `nullable: false`, `computed` to `@Computed((row) => f.string().as(...))` or `@Computed((row) => row.books.count())`, and a schema's `fields` likewise; a schema's other options to the sections chained after it, its column-level `references` to `.references({ authorId: () => User })` and its `aggregates` to `.relations()`' second callback, and each index, check and trigger entry, in `@Entity` and a schema, to the helper its callback is handed: `(post, index) => [index([post.title], 'by_title')]`.
+- A column's options to its builder, last, after the rewrites above: `@Id()` and `@Field({ type: String, nullable: true, length: 80 })` to `@Field(f.number().id())` and `@Field(f.string().nullable().length(80))`, a NOT NULL column losing its `nullable: false`, `computed` to `@Computed((row) => f.string().as(...))` or `@Computed((row) => row.books.count())`, and a defined entity's `fields` likewise; its other options to the sections chained after it, and its `aggregates` to `.relations()`' second callback. A defined column's foreign key becomes a relation: its `references` is dropped where a relation joins on the column (by `(order) => order.customerId`, by `[{ local, foreign }]` pairs, or as the ORM infers the one column naming its target, written into it), its `onDelete` moved into that relation, and where none joins, a `manyToOne` named as the column less its `Id` is written for it: `customer: () => rel.manyToOne(Customer, { references: (order) => order.customerId })`. Then each index, check and trigger entry, in `@Entity` and `defineEntity`, goes to the helper its callback is handed: `(post, index) => [index([post.title], 'by_title')]`.
 - A migration's columns to the same methods: `table.string('email', { length: 80, nullable: true })` to `table.string('email').length(80).nullable()`, `.defaultValue()` to `.default()`, `.primaryKey()` to `.id()`, `.computed()` to `.as()`, and `.notNullable()` dropped.
 - `@Index`, `@Trigger` and `@Filter` into `@Entity`'s `indexes`, `triggers` and `filters`, each decorator's comments kept above its entry; a class with no `@Entity` becomes `@Entity({ abstract: true, ... })`, a base that is never a table.
 - Members named by string to callbacks: `mappedBy: 'author'` to `(post) => post.author`, and `include`, `references` and `@Entity`/`defineEntity`'s `indexes` and `hooks` likewise: `{ columns: (post) => [post.title] }`.
 - `references: (post) => post.authorId` on a to-one (`@ManyToOne`, `@OneToOne`, or in `defineEntity`) 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 `sql`, importing it, on entities and in the migration builder.
-- A class registered with `defineEntity(Post, { ... })` to the schema it declares, `export const Post = defineEntity({ name: 'Post', ... })` and `export type Post = InstanceType<typeof Post>`, the class removed and a table it named kept as `table`: each relation as `author: () => rel.manyToOne(User, { ... })`, a computed field under `computed`, a relation aggregate under `aggregates`, a hook's method as a function of the row (`this` read as the row), and the same class's `defineField`, `defineId`, `defineRelation`, `defineHook`, `defineIndex`, `defineTrigger` and `defineFilter` folded in.
+- A class registered with `defineEntity(Post, { ... })` to the `defineEntity({ ... })` call it stands for, whole or not at all: `export const Post = defineEntity({ name: 'Post', fields })` with its sections chained, as a defined entity's options are above, and `export type Post = InstanceType<typeof Post>`. The class is removed and a table it named kept as `table`; a field stating no `type` takes the one its property declares (`authorId?: number | null` is `f.number().nullable()`), each relation becomes `author: () => rel.manyToOne(User, { ... })`, a relation aggregate a derived field (`(post) => ({ total: () => post.comments.count() })`), a hook's method a function of the row (`this` read as the row), and the same class's `defineField`, `defineId`, `defineRelation`, `defineHook`, `defineIndex`, `defineTrigger` and `defineFilter` are folded in.
 - A JSON index entry to the path read off the column's ref: `{ column: post.kind, jsonPath: { path: 'theme', type: Number } }` to `{ column: post.kind.theme, type: Number }`, and a `jsonArray`'s element type to `type: [String]`.
 - `col('cost')` to the ref it names, ``(product) => sql`${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.
 - `$exclude` to a `$select` leaving its fields out: `$exclude: { password: true }` to `$select: { password: false }`, at every depth of `$populate`.
@@ -51,16 +51,17 @@ Reported with what to do, never guessed:
 - An `$exclude` it cannot read, or one beside a `$select`: merge it in, each field as `field: false`.
 - A to-one onto a composite key: declare a column per key and pair each with it in `references`.
 - A to-one whose `<relation>Id` is not a declared column: an undecorated property, or a `defineEntity` whose `fields` leave it out.
-- A class `defineEntity` registers that a schema cannot declare as it is: one that extends another class, has a method no hook runs or is decorated as well; options it cannot read; a class registered in another file, or an entity that is no class declared in the file.
+- A class `defineEntity` registers that `defineEntity({ ... })` cannot declare as it is: one that extends another class, has a method no hook runs or is decorated as well; options it cannot read, or a column or section its chain cannot write; a class registered in another file, or an entity that is no class declared in the file. It is left as written, each reason reported.
+- A defined column's foreign key no relation can take: one whose relation name (the column less its `Id`) is taken or cannot be read off it, a key with no type of its own (`f.references(() => Order)`), or an `onDelete` its relation contradicts.
 - A definer on a decorated class (`defineIndex(Post, ...)`), and `@Entity`'s `fields`, `relations`, `hooks` and `extends`: each is a decorator, or the class's own `extends`, now.
-- A property typed more narrowly than its schema derives, as a note: a `Json<T>` column wants `shape`, a string-literal union `enum`.
+- A property typed more narrowly than `defineEntity` derives, as a note: a `Json<T>` column wants a Standard Schema, a string-literal union `enum`.
 - A partial-index `where` string that interpolates, since `sql` would bind what the template spliced in.
 - A JSON index entry whose `path` is not a string literal, or that takes an option besides `path`, `type` and `length`.
 - 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) => sql`lower(${user.email})` ``, and never the text.
 - A file that already names something the codemod would write (`sql`, `refs`, `idKey`, `f`, a renamed export): left unchanged and reported, since the new import would shadow it or be shadowed.
 - A property whose type maps to no column (`Json<T>`, a vector, a mixed union).
-- A column option it cannot write as a method: `shape` on a column that is not JSON, a migration column's options passed as a variable, or a flag such as `unique: isUnique` that no literal states.
+- A column option it cannot write as a method: a `shape` a JSON column no longer takes, a migration column's options passed as a variable, or a flag such as `unique: isUnique` that no literal states.
 - A `@Field`/`@Id` with no `type`, and a relation with no `entity`: declare the column as a builder (`f.string()`) and name the target (`entity: () => Target`). A branded string id's column, `f.uuid()` or `f.string()`, is yours to pick.
 - `Relation<T>` imported from `uql-orm`, which no longer exports it: write the property's type without it, and drop the import.
 

package/dist/builders.d.ts

@@ -8,7 +8,7 @@ export declare function isBuilder(node: ts.Expression): boolean;
 /** The names a builder writes, which the file must not bind otherwise. */
 export declare const BUILDER_NAMES: ReadonlySet<string>;
 /**
- * Writes entity definitions as column builders, `@Field(f.string().nullable())`, and a schema as its columns and a
+ * Writes entity definitions as column builders, `@Field(f.string().nullable())`, and a defined entity as its columns and a
  * chain of sections. Read off the text the other rewrites produced, so it only moves what is written; whatever it
  * cannot write faithfully is left as it is and reported.
  */
@@ -16,3 +16,13 @@ export declare function toBuilders(fileName: string, text: string, { locate, tak
     readonly locate?: (at: number) => string;
     readonly taken: ReadonlySet<string>;
 }): BuildersResult;
+/**
+ * A defined entity's statement, `const X = defineEntity({...})`, its call written as a chain and the builders it writes, or why
+ * it cannot be.
+ */
+export declare function chainedEntity(text: string): {
+    readonly text: string;
+    readonly builders: ReadonlySet<string>;
+} | {
+    readonly reasons: readonly string[];
+};

package/dist/builders.js

@@ -1,11 +1,12 @@
 import ts from 'typescript';
 import { call, flag, flagOrCall } from './columnMethods.js';
 import { formatFindings, locationAt } from './context.js';
-import { applyEdits, editedText, inserted, replaced, replacingUses, reparsedAgain, unedited, } from './edits.js';
-import { deadImports, importRemovalEdits, importText, spelledNames, uqlImportDeclarations } from './imports.js';
+import { FOREIGN_KEY_IN_DEFINED, NO_KEY_TYPE, nameClash, ON_DELETE_ON_RELATION } from './definedMessages.js';
+import { CHAINED_OPTIONS, FIRST_CALL_OPTIONS } from './definedOptions.js';
+import { applyEdits, editedText, replaced, replacingUses, reparsedAgain, unedited, } from './edits.js';
+import { importEdits } from './imports.js';
 import { isCallback, paramFor } from './keyMaps.js';
-import { CHAINED_OPTIONS, FIRST_CALL_OPTIONS } from './schemaOptions.js';
-import { chainOf, decoratorName, decoratorsOf, FIELD_DECORATORS, identifierText, identifierUses, indentOf, indentUnit, keyOf, objectLiteral, optionsOf, propertiesByKey, propertyAssignment, propertyValue, } from './syntax.js';
+import { chainOf, decoratorName, decoratorsOf, FIELD_DECORATORS, identifierText, identifierUses, indentOf, indentUnit, keyOf, objectLiteral, objectProperties, optionsOf, propertiesByKey, propertyAssignment, propertyKey, propertyValue, } from './syntax.js';
 /** The column type each constructor implies, and the builder it is now. */
 const CONSTRUCTORS = {
     String: 'f.string()',
@@ -41,8 +42,8 @@ const METHODS = [
     ['onDelete', call('onDelete')],
 ];
 /** What a constructor or `nullable()`/`id()` already said, so no method repeats it. */
-const SAID_BY_SHAPE = new Set(['type', 'nullable', 'isId', 'enum', 'shape', 'version', 'computed', 'stored']);
-const KNOWN = new Set([...SAID_BY_SHAPE, ...METHODS.map(([option]) => option)]);
+const SAID_BY_CONSTRUCTOR = new Set(['type', 'nullable', 'isId', 'enum', 'version', 'computed', 'stored']);
+const KNOWN = new Set([...SAID_BY_CONSTRUCTOR, ...METHODS.map(([option]) => option)]);
 /** The options a literal states, each by its key, or why it cannot be read. */
 function optionsByKey(node) {
     const options = optionsOf(node);
@@ -100,9 +101,6 @@ function decimalOf(text) {
 function constructorOf(options, text) {
     const type = text('type');
     const members = text('enum');
-    if (options.has('shape') && type !== "'json'" && type !== "'jsonb'") {
-        return { message: "has a 'shape' on a column that is no JSON: only a JSON column holds a payload" };
-    }
     if (options.has('version')) {
         text('version');
         if (type === undefined || type === 'Number')
@@ -134,8 +132,7 @@ function constructorOf(options, text) {
         return NAMED_TYPES[literal];
     }
     if (literal === 'json' || literal === 'jsonb') {
-        const shape = text('shape');
-        return `f.${literal}(${shape ?? ''})`;
+        return `f.${literal}()`;
     }
     if (literal === 'vector') {
         const dimensions = text('dimensions');
@@ -235,9 +232,9 @@ function computedDecorator(call, options, computed, findings, used) {
 export function isBuilder(node) {
     return identifierText(chainOf(node).root) === 'f';
 }
-/** The options a schema's first call keeps. */
+/** The options a defined entity's first call keeps. */
 const FIRST_CALL = new Set(FIRST_CALL_OPTIONS);
-/** Every key a schema's `defineEntity` options may state, as its first call or as a section. */
+/** Every key `defineEntity`'s options may state, as its first call or as a section. */
 const SCHEMA_KEYS = new Set([
     ...FIRST_CALL,
     ...CHAINED_OPTIONS,
@@ -245,14 +242,14 @@ const SCHEMA_KEYS = new Set([
     'aggregates',
 ]);
 /** `defineEntity({ fields: {...}, relations, ... })` as its first call and a chain of sections. */
-function schemaEdits(call, findings, used) {
+function definedEdits(call, findings, used) {
     const options = objectLiteral(call.arguments[0]);
     const fields = options && objectLiteral(propertyValue(options, 'fields'));
     const chained = options?.properties.some((prop) => !FIRST_CALL.has(keyOf(prop)));
-    if (!options || !fields || (!chained && fields.properties.every((prop) => isSchemaColumn(prop)))) {
+    if (!options || !fields || (!chained && fields.properties.every((prop) => isDefinedColumn(prop)))) {
         return [];
     }
-    const param = schemaParam(call);
+    const param = definedParam(call);
     const unknown = options.properties.filter((prop) => !SCHEMA_KEYS.has(keyOf(prop)));
     if (unknown.length) {
         findings.push({
@@ -261,34 +258,59 @@ function schemaEdits(call, findings, used) {
         });
         return [];
     }
-    const references = [];
     const field = propertyAssignment(options, 'fields');
-    const columns = fields.properties.map((prop) => {
-        if (!ts.isPropertyAssignment(prop)) {
+    const relations = propertyValue(options, 'relations');
+    const aggregates = propertyValue(options, 'aggregates');
+    const read = fields.properties.map((prop) => ({
+        prop,
+        column: ts.isPropertyAssignment(prop) ? definedColumn(prop.initializer) : undefined,
+    }));
+    const { joins, inferred } = joinsOf(relations, targetsOf(read), param);
+    const targets = {
+        param,
+        rel: (relations && ts.isArrowFunction(relations) && identifierText(relations.parameters[0]?.name)) || 'rel',
+        joins,
+        insertable: !relations || returnedLiteral(relations) !== undefined,
+    };
+    const start = {
+        named: new Set([
+            fields,
+            objectLiteral(propertyValue(options, 'computed')),
+            returnedLiteral(relations),
+            returnedLiteral(aggregates),
+        ]
+            .flatMap((literal) => objectProperties(literal))
+            .map((prop) => propertyKey(prop.name))),
+        added: [],
+        options: new Map([...inferred].map(([relation, reference]) => [relation, [reference]])),
+    };
+    const claimed = claimColumns(read, start, targets);
+    const columns = read.map(({ prop, column }) => {
+        if (!ts.isPropertyAssignment(prop) || !column) {
             findings.push({ node: prop, message: `cannot write '${prop.getText()}' as a column: write its options inline` });
             return undefined;
         }
-        const key = prop.name.getText();
-        const built = isBuilder(prop.initializer)
-            ? builtSchemaColumn(prop.initializer, key, references)
-            : schemaColumnOf(prop.initializer, key, references);
-        if (typeof built !== 'string') {
-            findings.push({ node: prop, message: `'${key}' ${built.message}` });
+        const key = propertyKey(prop.name) ?? prop.name.getText();
+        if ('message' in column) {
+            findings.push({ node: prop, message: `'${key}' ${column.message}` });
+            return undefined;
+        }
+        const problem = claimed.problems.get(prop);
+        if (problem) {
+            findings.push({ node: prop, message: `'${key}' ${problem}` });
             return undefined;
         }
-        return withValue(prop, built);
+        return withValue(prop, column.builder);
     });
     const sections = CHAINED_OPTIONS.flatMap((section) => {
         const value = propertyValue(options, section);
         return value ? [chainedSection(section, value, param, findings)] : [];
     });
-    if (references.length) {
-        sections.push(`.references({ ${references.join(', ')} })`);
-    }
-    const relations = propertyValue(options, 'relations');
-    const aggregates = propertyValue(options, 'aggregates');
-    if (relations || aggregates) {
-        sections.push(`.relations(${relations?.getText() ?? '() => ({})'}${aggregates ? `, ${aggregates.getText()}` : ''})`);
+    const indent = indentOf(call);
+    const unit = indentUnit(call.getSourceFile());
+    const related = relationsText(relations, targets.rel, claimed.claims, fields.getText().includes('\n') ? `${indent}${unit}` : undefined, unit);
+    if (related || aggregates) {
+        sections.push(`.relations(${related ?? '() => ({})'}${aggregates ? `, ${aggregates.getText()}` : ''})`);
     }
     const written = columns.filter((it) => it !== undefined);
     if (written.length !== columns.length || sections.some((it) => it === undefined)) {
@@ -298,69 +320,237 @@ function schemaEdits(call, findings, used) {
     const kept = options.properties
         .filter((prop) => FIRST_CALL.has(keyOf(prop)))
         .map((prop) => (prop === field ? withValue(field, literal(fields, written)) : prop.getFullText()));
-    const indent = indentOf(call);
     return [
-        replaced(call, `${call.expression.getText()}(${literal(options, kept)})${sections.map((it) => `\n${indent}  ${it}`).join('')}`),
+        replaced(call, `${call.expression.getText()}(${literal(options, kept)})${sections.map((it) => `\n${indent}${unit}${it}`).join('')}`),
     ];
 }
-/** The parameter a schema's callbacks are named after: its `name` where that is a literal, else its variable's. */
-function schemaParam(call) {
+/** The parameter a defined entity's callbacks are named after: its `name` where that is a literal, else its variable's. */
+function definedParam(call) {
     const options = objectLiteral(call.arguments[0]);
     const name = options && /^'(.+)'$/.exec(propertyValue(options, 'name')?.getText() ?? '')?.[1];
     return paramFor(name ?? identifierText(variableOf(call)));
 }
-/** A schema column written as options, through {@link schemaColumn}, or why it cannot be. */
-function schemaColumnOf(node, key, references) {
-    const column = optionsByKey(node);
-    return typeof column === 'string'
-        ? { message: `cannot be written as a builder because ${column}` }
-        : schemaColumn(column, key, references);
+/** A defined column's builder off its options or chain, its `references` and `onDelete` taken out to move to a relation. */
+function definedColumn(node) {
+    if (isBuilder(node)) {
+        const methods = chainMethods(node);
+        const references = methods.get('references');
+        if (!references) {
+            return { builder: node.getText() };
+        }
+        const target = targetOf(references.call.arguments[0]);
+        if (identifierText(references.receiver) === 'f' || !target) {
+            return { message: target ? NO_KEY_TYPE : FOREIGN_KEY_IN_DEFINED };
+        }
+        const onDelete = methods.get('onDelete');
+        const cut = [references, ...(onDelete ? [onDelete] : [])].map((method) => ({
+            start: method.receiver.getEnd() - node.getStart(),
+            end: method.call.getEnd() - node.getStart(),
+            text: '',
+        }));
+        return {
+            builder: applyEdits(node.getText(), cut),
+            key: { target, onDelete: onDelete?.call.arguments[0]?.getText() },
+        };
+    }
+    const options = optionsByKey(node);
+    if (typeof options === 'string') {
+        return { message: `cannot be written as a builder because ${options}` };
+    }
+    const references = options.get('references');
+    const target = references && targetOf(references);
+    if (references && !target) {
+        return { message: FOREIGN_KEY_IN_DEFINED };
+    }
+    if (target && !options.has('type')) {
+        return { message: NO_KEY_TYPE };
+    }
+    const built = columnBuilder(new Map([...options].filter(([option]) => !target || (option !== 'references' && option !== 'onDelete'))), false);
+    if (typeof built !== 'string') {
+        return built;
+    }
+    return target
+        ? { builder: built, key: { target, onDelete: options.get('onDelete')?.getText() } }
+        : { builder: built };
+}
+/** The entity a `() => Target` getter names, as its text. */
+function targetOf(getter) {
+    return getter && ts.isArrowFunction(getter) && !ts.isBlock(getter.body) ? getter.body.getText() : undefined;
+}
+/** Each column's foreign key target, for the columns naming one. */
+function targetsOf(read) {
+    return new Map(read.flatMap(({ prop, column }) => column && 'key' in column && column.key ? [[prop.name?.getText(), column.key.target]] : []));
+}
+/** The defined entity's columns' foreign keys claimed in turn, the problem of each column by its name node. */
+function claimColumns(read, start, targets) {
+    const problems = new Map();
+    const claims = read.reduce((state, { prop, column }) => {
+        if (!ts.isPropertyAssignment(prop) || !column || !('key' in column) || !column.key) {
+            return state;
+        }
+        const outcome = claimKey(prop.name, column.key, state, targets);
+        if (outcome.problem) {
+            problems.set(prop, outcome.problem);
+        }
+        return outcome.claims;
+    }, start);
+    return { claims, problems };
+}
+/**
+ * A column's foreign key moved into the to-one joining on it, with its `onDelete`, else into a `manyToOne` written for
+ * it, named as the column less its `Id`; or why it cannot be.
+ */
+function claimKey(name, { target, onDelete }, claims, targets) {
+    const key = name.getText();
+    const join = targets.joins.get(key);
+    if (join) {
+        return onDelete ? movedOnDelete(join, onDelete, claims) : { claims };
+    }
+    const relation = ts.isIdentifier(name) ? /^(.+?)(?:Id|_id)$/.exec(key)?.[1] : undefined;
+    if (!relation || claims.named.has(relation) || !targets.insertable) {
+        return { claims, problem: FOREIGN_KEY_IN_DEFINED };
+    }
+    const written = [
+        `references: (${targets.param}) => ${targets.param}.${key}`,
+        ...(onDelete ? [`onDelete: ${onDelete}`] : []),
+    ];
+    return {
+        claims: {
+            ...claims,
+            named: new Set([...claims.named, relation]),
+            added: [...claims.added, `${relation}: () => ${targets.rel}.manyToOne(${target}, { ${written.join(', ')} })`],
+        },
+    };
+}
+/** Writes a column's `onDelete` into the to-one joining on it, or says why not: it states another, or options none can be written into. */
+function movedOnDelete(relation, onDelete, claims) {
+    const written = `onDelete: ${onDelete}`;
+    const options = relation.arguments[1];
+    const literal = objectLiteral(options);
+    const stated = literal ? propertyValue(literal, 'onDelete')?.getText() : undefined;
+    const current = claims.options.get(relation) ?? [];
+    const pending = current.find((option) => option.startsWith('onDelete: '));
+    if ((options && !literal) || (stated ?? onDelete) !== onDelete || (pending ?? written) !== written) {
+        return { claims, problem: ON_DELETE_ON_RELATION };
+    }
+    return stated || pending
+        ? { claims }
+        : { claims: { ...claims, options: new Map(claims.options).set(relation, [...current, written]) } };
+}
+/** The relation calls a defined entity's `relations` returns, one per relation. */
+function relationCalls(relations) {
+    return objectProperties(returnedLiteral(relations)).flatMap((prop) => {
+        const relation = ts.isArrowFunction(prop.initializer) ? prop.initializer.body : undefined;
+        return relation && ts.isCallExpression(relation) ? [relation] : [];
+    });
+}
+/** The object literal a callback returns, `(rel) => ({ ... })`, or nothing where it returns none so. */
+function returnedLiteral(callback) {
+    const body = callback && ts.isArrowFunction(callback) && !ts.isBlock(callback.body) ? callback.body : undefined;
+    return objectLiteral(body && ts.isParenthesizedExpression(body) ? body.expression : body);
 }
 /**
- * A schema column's builder, its foreign key moved into `.references()`, where its target is read once every entity
- * exists: written in `fields`, it would read the target while that target's own type is still being inferred.
+ * The to-one joining on each column: by the `references` it names, `(row) => row.column` or pairs of `local`s, else by
+ * the ORM's inference, the one column whose foreign key names its target, whose `references` is written as inferred.
  */
-function schemaColumn(options, key, references) {
-    const target = options.get('references');
-    if (!target) {
-        return columnBuilder(options, false);
+function joinsOf(relations, targets, param) {
+    const joins = new Map();
+    const inferred = new Map();
+    for (const relation of relationCalls(relations)) {
+        const named = namedColumns(relation);
+        for (const column of named ?? []) {
+            if (!joins.has(column))
+                joins.set(column, relation);
+        }
+        const target = relation.arguments[0]?.getText();
+        const matching = [...targets].filter(([, named]) => named === target).map(([key]) => key);
+        const column = matching.length === 1 ? matching[0] : undefined;
+        if (!named && isToOne(relation) && writableOptions(relation) && column && !joins.has(column)) {
+            inferred.set(relation, `references: (${param}) => ${param}.${column}`);
+            joins.set(column, relation);
+        }
     }
-    if (!options.has('type')) {
-        return { message: "references another entity but states no 'type': state the column's, as its key's" };
+    return { joins, inferred };
+}
+/** The columns a relation's `references` names on its local side, or nothing where it names none it can read. */
+function namedColumns(relation) {
+    const options = objectLiteral(relation.arguments[1]);
+    const references = options && propertyValue(options, 'references');
+    if (!references) {
+        return undefined;
     }
-    references.push(referenceEntry(key, target.getText(), options.get('onDelete')?.getText()));
-    return columnBuilder(new Map([...options].filter(([option]) => option !== 'references' && option !== 'onDelete')), false);
+    const local = ts.isArrowFunction(references) ? identifierText(references.parameters[0]?.name) : undefined;
+    const column = (node) => node && ts.isPropertyAccessExpression(node) && identifierText(node.expression) === local
+        ? node.name.text
+        : undefined;
+    const body = local && ts.isArrowFunction(references) ? references.body : undefined;
+    if (body && ts.isArrayLiteralExpression(body)) {
+        const locals = body.elements.map((pair) => {
+            const literal = objectLiteral(pair);
+            return column(literal && propertyValue(literal, 'local'));
+        });
+        return locals.every((it) => it !== undefined) ? locals : [];
+    }
+    const single = body && ts.isExpression(body) ? column(body) : undefined;
+    return single ? [single] : [];
+}
+function isToOne(relation) {
+    return ts.isPropertyAccessExpression(relation.expression) && relation.expression.name.text === 'manyToOne';
+}
+/** Whether a relation's options are absent or a literal, the only kind an option can be written into. */
+function writableOptions(relation) {
+    return relation.arguments.length < 2 || objectLiteral(relation.arguments[1]) !== undefined;
+}
+/**
+ * The relations' text, each to-one's options written into its relation and each relation added for a foreign key
+ * appended, or nothing where there are none. A section of its own is laid out a line per relation, a `unit` in from
+ * the section's `indent`, where one is given.
+ */
+function relationsText(relations, rel, { options, added }, indent, unit) {
+    if (!relations) {
+        if (!added.length)
+            return undefined;
+        const listed = indent === undefined
+            ? `{ ${added.join(', ')} }`
+            : `{\n${added.map((entry) => `${indent}${unit}${entry},\n`).join('')}${indent}}`;
+        return `(${rel}) => (${listed})`;
+    }
+    const base = relations.getStart();
+    const edits = [...options].flatMap(([relation, written]) => written.length ? [withOptions(relation, written, base)] : []);
+    const literal = returnedLiteral(relations);
+    if (literal && added.length) {
+        edits.push(appendedEntries(literal, added, base));
+    }
+    return applyEdits(relations.getText(), edits);
+}
+/** The edit writing `options` into a relation call: after its options' last, else as options after its target. */
+function withOptions(relation, options, base) {
+    const literal = objectLiteral(relation.arguments[1]);
+    const last = literal?.properties.at(-1);
+    if (literal && !last) {
+        return { start: literal.getStart() - base, end: literal.getEnd() - base, text: `{ ${options.join(', ')} }` };
+    }
+    const at = (last ?? relation.arguments[0]).getEnd() - base;
+    return { start: at, end: at, text: last ? `, ${options.join(', ')}` : `, { ${options.join(', ')} }` };
 }
-/** One entry of `.references()`: the target's getter, with its `onDelete` where one is stated. */
-function referenceEntry(key, getter, action) {
-    return action ? `${key}: { entity: ${getter}, onDelete: ${action} }` : `${key}: ${getter}`;
+/** The edit appending `entries` to an object literal, laid out as its own entries are. */
+function appendedEntries(literal, entries, base) {
+    const last = literal.properties.at(-1);
+    if (!last) {
+        return { start: literal.getStart() - base, end: literal.getEnd() - base, text: `{ ${entries.join(', ')} }` };
+    }
+    const separator = literal.getText().includes('\n') ? `,\n${indentOf(last)}` : ', ';
+    const at = last.getEnd() - base;
+    return { start: at, end: at, text: entries.map((entry) => `${separator}${entry}`).join('') };
 }
-/** Whether a schema column is a builder naming no foreign key, which a schema's `fields` keep as they are. */
-function isSchemaColumn(prop) {
+/** Whether a defined column is a builder naming no foreign key, which a defined entity's `fields` keep as they are. */
+function isDefinedColumn(prop) {
     return (ts.isPropertyAssignment(prop) && isBuilder(prop.initializer) && !chainMethods(prop.initializer).has('references'));
 }
 /** Each method a builder chain calls, by name. */
 function chainMethods(node) {
     return new Map(chainOf(node).methods.map((method) => [method.name, method]));
 }
-/** A builder in `fields` with its foreign key, `.references(() => X)` and `.onDelete()`, moved into `.references()`. */
-function builtSchemaColumn(node, key, references) {
-    const methods = chainMethods(node);
-    const target = methods.get('references');
-    if (!target) {
-        return node.getText();
-    }
-    if (identifierText(target.receiver) === 'f') {
-        return { message: "references another entity but states no type: write its builder, as its key's" };
-    }
-    const onDelete = methods.get('onDelete');
-    references.push(referenceEntry(key, target.call.arguments[0]?.getText(), onDelete?.call.arguments[0]?.getText()));
-    // Each method is cut out with the chain before it: from that receiver's end to the call's.
-    const cut = [onDelete, target].flatMap((method) => method
-        ? [{ start: method.receiver.getEnd() - node.getStart(), end: method.call.getEnd() - node.getStart(), text: '' }]
-        : []);
-    return applyEdits(node.getText(), cut);
-}
 /**
  * An object literal of `properties`, each its full text with its comments, laid out as `node` was: on one line
  * where it was written on one, a property a line otherwise.
@@ -490,7 +680,7 @@ function entityEdits(cls, findings) {
         });
     });
 }
-/** A schema's computed map as what its section returns: each a column `as()` its SQL. */
+/** A defined entity's computed map as what its section returns: each a column `as()` its SQL. */
 function computedSection(value, param) {
     const map = objectLiteral(value);
     const entries = map?.properties.map((prop) => {
@@ -524,7 +714,7 @@ export const BUILDER_NAMES = new Set(['f', 'Computed']);
 /** Whether the file declares anything this pass rewrites. */
 const REWRITES = /@(?:Field|Id)\(|\bdefineEntity\(\s*\{|@Entity\(\s*\{/;
 /**
- * Writes entity definitions as column builders, `@Field(f.string().nullable())`, and a schema as its columns and a
+ * Writes entity definitions as column builders, `@Field(f.string().nullable())`, and a defined entity as its columns and a
  * chain of sections. Read off the text the other rewrites produced, so it only moves what is written; whatever it
  * cannot write faithfully is left as it is and reported.
  */
@@ -544,9 +734,9 @@ export function toBuilders(fileName, text, { locate, taken }) {
             edits.push(...entityEdits(node, findings));
         }
         if (ts.isCallExpression(node) && identifierText(node.expression) === 'defineEntity') {
-            const schema = schemaEdits(node, findings, used);
-            if (schema.length) {
-                edits.push(...schema);
+            const defined = definedEdits(node, findings, used);
+            if (defined.length) {
+                edits.push(...defined);
                 return;
             }
         }
@@ -562,27 +752,32 @@ export function toBuilders(fileName, text, { locate, taken }) {
     if (clash) {
         return {
             ...unedited(text),
-            unresolved: [
-                ...unresolved,
-                `${located(0)}: '${clash}' is already named here, and the codemod writes it: rename that, then run again`,
-            ],
+            unresolved: [...unresolved, `${located(0)}: ${nameClash(clash)}: rename that, then run again`],
         };
     }
-    return { ...reparsedAgain(fileName, editedText(text, edits), (edited) => importEdits(edited, used)), unresolved };
+    return {
+        ...reparsedAgain(fileName, editedText(text, edits), (edited) => importEdits(edited, used, FIELD_DECORATORS)),
+        unresolved,
+    };
 }
-/** Imports what the pass now writes, `f` and `Computed`, and no longer the field decorators it replaced, once unspelled. */
-function importEdits(source, used) {
-    const [declaration] = uqlImportDeclarations(source, true);
-    if (!declaration) {
-        return used.size ? [{ start: 0, end: 0, text: `${importText('import', [...used].toSorted(), 'uql-orm')}\n` }] : [];
-    }
-    const names = new Set(declaration.elements.map((it) => it.name.text));
-    const added = [...used].filter((name) => !names.has(name)).toSorted();
-    const dead = deadImports(declaration.elements, FIELD_DECORATORS, spelledNames(source));
-    const first = declaration.elements.find((it) => !dead.includes(it));
-    if (!first) {
-        return [replaced(declaration.declaration, importText('import', added, 'uql-orm'))];
-    }
-    const removals = importRemovalEdits(declaration.declaration, declaration.elements, dead);
-    return added.length ? [...removals, inserted(first, `${added.join(', ')}, `)] : removals;
+/**
+ * A defined entity's statement, `const X = defineEntity({...})`, its call written as a chain and the builders it writes, or why
+ * it cannot be.
+ */
+export function chainedEntity(text) {
+    const source = ts.createSourceFile('/entity.ts', text, ts.ScriptTarget.Latest, true);
+    const findings = [];
+    const used = new Set();
+    const edits = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && identifierText(node.expression) === 'defineEntity') {
+            edits.push(...definedEdits(node, findings, used));
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(source);
+    return findings.length
+        ? { reasons: findings.map(({ message }) => message) }
+        : { text: applyEdits(text, edits), builders: used };
 }

package/dist/definedEntity.d.ts

@@ -0,0 +1,15 @@
+import { type Pass } from './edits.js';
+export type DefinedResult = Pass & {
+    readonly unresolved: string[];
+    readonly notes: string[];
+};
+/**
+ * Declares each class `defineEntity(Class, options)` registered as `defineEntity({ name, fields })` and its
+ * chain of sections, folding the string-keyed definers of the same class in. Read off the text the other rewrites
+ * produced, whose options already name members by callback, so it only moves what is written. An entity it cannot
+ * declare faithfully, `taken` naming a builder it writes among them, is left as written and reported.
+ */
+export declare function toDefinedEntities(fileName: string, text: string, { locate, taken }: {
+    readonly locate?: (at: number) => string;
+    readonly taken: ReadonlySet<string>;
+}): DefinedResult;

package/dist/{schemaEntity.js → definedEntity.js}

@@ -1,12 +1,14 @@
 import ts from 'typescript';
+import { chainedEntity } from './builders.js';
 import { formatFindings, locationAt } from './context.js';
+import { nameClash } from './definedMessages.js';
+import { KEPT_OPTIONS } from './definedOptions.js';
 import { CLASS_DEFINERS, definerCall } from './definers.js';
 import { editedText, removeStatement, replaced, replacingUses, reparsedAgain, unedited, } from './edits.js';
-import { unusedImportEdits } from './imports.js';
+import { importEdits } from './imports.js';
 import { memberKey, paramFor, quoted } from './keyMaps.js';
-import { KEPT_OPTIONS } from './schemaOptions.js';
 import { arrayElements, decoratorsOf, freeName, hasModifier, identifierText, identifierUses, indentOf, indentUnit, isNamedProperty, objectLiteral, objectProperties, propertyKey, propertyValue, } from './syntax.js';
-/** Imports a converted file may no longer read: the definers folded in, and the brands a schema derives. */
+/** Imports a converted file may no longer read: the definers folded in, and the brands a defined entity derives. */
 const FOLDED_IMPORTS = new Set([
     ...Object.keys(CLASS_DEFINERS).filter((name) => name !== 'defineEntity'),
     'idKey',
@@ -47,12 +49,12 @@ function readsAs(value, shape) {
 /** What a class-form relation said that a `rel` builder says by its name and first argument. */
 const RELATION_SHAPE = new Set(['cardinality', 'entity']);
 /**
- * Declares each class `defineEntity(Class, options)` registered as the schema `defineEntity({ name, ... })`,
- * folding the string-keyed definers of the same class in. Read off the text the other rewrites produced,
- * whose options already name members by callback, so it only moves what is written. An entity it cannot
- * declare faithfully is left as written and reported.
+ * Declares each class `defineEntity(Class, options)` registered as `defineEntity({ name, fields })` and its
+ * chain of sections, folding the string-keyed definers of the same class in. Read off the text the other rewrites
+ * produced, whose options already name members by callback, so it only moves what is written. An entity it cannot
+ * declare faithfully, `taken` naming a builder it writes among them, is left as written and reported.
  */
-export function toSchemaEntities(fileName, text, locate) {
+export function toDefinedEntities(fileName, text, { locate, taken }) {
     if (!CLASS_FORM_CALL.test(text)) {
         return { ...unedited(text), unresolved: [], notes: [] };
     }
@@ -62,6 +64,7 @@ export function toSchemaEntities(fileName, text, locate) {
     const unresolved = [];
     const notes = [];
     const edits = [];
+    const written = new Set();
     const registrations = collectRegistrations(source, unresolved);
     const entityCallOf = (calls) => calls.find(({ definer }) => definer === 'defineEntity')?.call;
     for (const [name, { cls, calls }] of registrations) {
@@ -79,26 +82,38 @@ export function toSchemaEntities(fileName, text, locate) {
             });
             continue;
         }
-        const schema = schemaOf(name, cls, calls, entityCall, unit);
-        if ('message' in schema) {
-            unresolved.push(schema);
+        const defined = definedOf(name, cls, calls, entityCall, unit);
+        if ('message' in defined) {
+            unresolved.push(defined);
             continue;
         }
-        notes.push(...schema.notes);
+        const chained = chainedEntity(defined.text);
+        if (!('text' in chained)) {
+            unresolved.push(...chained.reasons.map((reason) => ({ node: entityCall, message: `'${name}' is left as written: ${reason}` })));
+            continue;
+        }
+        const clash = [...chained.builders].find((builder) => taken.has(builder));
+        if (clash !== undefined) {
+            unresolved.push({ node: entityCall, message: `'${name}' is left as written: ${nameClash(clash)}` });
+            continue;
+        }
+        for (const builder of chained.builders)
+            written.add(builder);
+        notes.push(...defined.notes);
         edits.push(removeStatement(cls));
         for (const { call } of calls) {
-            edits.push(call === entityCall ? replaced(call.parent, indented(schema.text, call.parent)) : removeStatement(call.parent));
+            edits.push(call === entityCall ? replaced(call.parent, indented(chained.text, call.parent)) : removeStatement(call.parent));
         }
     }
     return {
         ...(edits.length
-            ? reparsedAgain(fileName, editedText(text, edits), (edited) => unusedImportEdits(edited, FOLDED_IMPORTS))
+            ? reparsedAgain(fileName, editedText(text, edits), (edited) => importEdits(edited, written, FOLDED_IMPORTS))
             : unedited(text)),
         unresolved: formatFindings(unresolved, located),
         notes: formatFindings(notes, located),
     };
 }
-/** The class a `defineEntity(Class, { extends })` names as its base, which its schema's const reads where it is declared. */
+/** The class a `defineEntity(Class, { extends })` names as its base, which its defined const reads where it is declared. */
 function baseName(entityCall) {
     const options = objectLiteral(entityCall.arguments[1]);
     return identifierText(options && propertyValue(options, 'extends'));
@@ -125,7 +140,7 @@ function collectRegistrations(source, unresolved) {
                 registrations.set(name, registration);
             }
             else if (read.definer === 'defineEntity') {
-                unresolved.push({ node, message: 'defineEntity takes a schema now: defineEntity({ name, fields, ... })' });
+                unresolved.push({ node, message: 'defineEntity takes options alone now: defineEntity({ name, fields, ... })' });
             }
             else {
                 unresolved.push({ node, message: removedDefiner(read.definer, textOf(read.entity)) });
@@ -140,7 +155,7 @@ function collectRegistrations(source, unresolved) {
 function removedDefiner(definer, entity) {
     return `${definer} was removed: register '${entity}' with defineEntity in this file, or decorate it (${CLASS_DEFINERS[definer]})`;
 }
-function schemaOf(name, cls, calls, entityCall, unit) {
+function definedOf(name, cls, calls, entityCall, unit) {
     const refused = (message) => ({ node: entityCall, message });
     const options = objectLiteral(entityCall.arguments[1]) ?? (entityCall.arguments[1] ? undefined : emptyOptions());
     if (!options || options.properties.some((prop) => !ts.isPropertyAssignment(prop))) {
@@ -150,15 +165,15 @@ function schemaOf(name, cls, calls, entityCall, unit) {
         return refused(`'${name}' extends a class: declare the base with defineEntity too and pass it as 'extends'`);
     }
     if (decoratorsOf(cls).length) {
-        return refused(`'${name}' is decorated as well: declare it one way, decorators or a schema`);
+        return refused(`'${name}' is decorated as well: declare it one way, decorators or defineEntity`);
     }
     const exported = hasModifier(cls, ts.SyntaxKind.ExportKeyword);
     if (hasModifier(cls, ts.SyntaxKind.DefaultKeyword)) {
-        return refused(`'${name}' is a default export: export the schema's const by name instead`);
+        return refused(`'${name}' is a default export: export its defineEntity const by name instead`);
     }
     const unread = objectProperties(options).find(({ name: key }) => !READ_OPTIONS.has(propertyKey(key)));
     if (unread) {
-        return refused(`'${textOf(unread.name)}' has no place in a schema: move it by hand`);
+        return refused(`'${textOf(unread.name)}' has no place in defineEntity: move it by hand`);
     }
     for (const [option, shape] of Object.entries(ENTRY_OPTIONS)) {
         const value = propertyValue(options, option);
@@ -171,6 +186,8 @@ function schemaOf(name, cls, calls, entityCall, unit) {
         name,
         param: paramFor(name),
         rel: freeName('rel', calls.map(({ call }) => call)),
+        self: freeName(paramFor(name), outerReads(paramFor(name), options, calls)),
+        declared: declaredTypes(cls),
         relations: new Set([
             ...objectProperties(propertyValue(options, 'relations')).map((it) => propertyKey(it.name)),
             ...calls.filter((read) => read.definer === 'defineRelation').map((read) => read.key),
@@ -182,6 +199,7 @@ function schemaOf(name, cls, calls, entityCall, unit) {
     };
     const gathered = {
         fields: [],
+        typed: false,
         computed: [],
         aggregates: [],
         relations: new Map(),
@@ -221,6 +239,7 @@ function schemaOf(name, cls, calls, entityCall, unit) {
     const fieldsValue = propertyValue(options, 'fields');
     const untouched = fieldsValue &&
         gathered.fields.length === objectProperties(fieldsValue).length &&
+        !gathered.typed &&
         !gathered.computed.length &&
         !gathered.aggregates.length;
     lines.push(`fields: ${untouched ? textOf(fieldsValue) : block(gathered.fields, unit)}`);
@@ -231,7 +250,7 @@ function schemaOf(name, cls, calls, entityCall, unit) {
         lines.push(`relations: (${scope.rel}) => (${block([...gathered.relations.values()], unit)})`);
     }
     if (gathered.aggregates.length) {
-        lines.push(`aggregates: (${scope.rel}) => (${block(gathered.aggregates, unit)})`);
+        lines.push(`aggregates: (${scope.self}) => (${block(gathered.aggregates, unit)})`);
     }
     for (const key of KEPT_OPTIONS) {
         const entries = gathered.kept.get(key);
@@ -283,7 +302,7 @@ function entriesOfValue(key, value) {
  * Adds what one registration declares to `gathered`: `options` for the `defineEntity` call, its arguments for an
  * incremental definer. Returns why it cannot, where it cannot.
  */
-function gather({ call, definer, key, options: third, rest }, options, gathered, { name, param, rel, relations, methods, hooked }) {
+function gather({ call, definer, key, options: third, rest }, options, gathered, { name, param, rel, self, relations, methods, hooked, declared }) {
     const unreadable = {
         node: call,
         message: `${definer}'s arguments could not be read: fold them into defineEntity by hand`,
@@ -306,8 +325,8 @@ function gather({ call, definer, key, options: third, rest }, options, gathered,
         gathered.hooks.set(event, runs);
         return undefined;
     };
-    const addField = (key, entry, fieldOptions, node) => {
-        const aggregate = key && aggregateEntry(`${name}.${key}`, key, fieldOptions, relations, rel);
+    const addField = (key, label, value, fieldOptions, node) => {
+        const aggregate = key && aggregateEntry(`${name}.${key}`, key, fieldOptions, relations, self);
         if (typeof aggregate === 'string') {
             gathered.aggregates.push(aggregate);
             return undefined;
@@ -315,6 +334,9 @@ function gather({ call, definer, key, options: third, rest }, options, gathered,
         if (aggregate) {
             return { node, message: aggregate.message };
         }
+        const type = key === undefined ? undefined : untyped(fieldOptions) && declared.get(key);
+        gathered.typed ||= !!type;
+        const entry = `${label}: ${type ? withOption(value, `type: ${type}`) : value}`;
         (isComputed(fieldOptions) ? gathered.computed : gathered.fields).push(entry);
         return undefined;
     };
@@ -332,7 +354,7 @@ function gather({ call, definer, key, options: third, rest }, options, gathered,
     };
     if (options) {
         for (const field of objectProperties(propertyValue(options, 'fields'))) {
-            const problem = addField(propertyKey(field.name), textOf(field), field.initializer, field);
+            const problem = addField(propertyKey(field.name), textOf(field.name), textOf(field.initializer), field.initializer, field);
             if (problem)
                 return problem;
         }
@@ -370,10 +392,11 @@ function gather({ call, definer, key, options: third, rest }, options, gathered,
         case 'defineId': {
             if (!key || !third)
                 return unreadable;
-            const value = definer === 'defineId' ? withIsId(third) : textOf(third);
+            const literal = objectLiteral(third);
+            const value = definer === 'defineId' ? literal && withOption(textOf(literal), 'isId: true') : textOf(third);
             if (!value)
                 return unreadable;
-            return addField(key, `${memberKey(key)}: ${value}`, third, call);
+            return addField(key, memberKey(key), value, third, call);
         }
         case 'defineRelation':
             return third && addRelation(key, third) ? undefined : unreadable;
@@ -398,18 +421,55 @@ function gather({ call, definer, key, options: third, rest }, options, gathered,
             return undefined;
     }
 }
-/** Whether a field's options compute it, which a schema declares under `computed`. */
+/** Whether a field's options compute it, which a defined entity declares under `computed`. */
 function isComputed(options) {
     const literal = objectLiteral(options);
     return !!literal && propertyValue(literal, 'computed') !== undefined;
 }
-/** `{ ...options, isId: true }` written into a literal's own text, or nothing where it is not one. */
-function withIsId(options) {
+/**
+ * The bodies of the field callbacks whose parameter is not `name`, where a `name` they read is the file's: a
+ * callback taking `name` reads its own under it, which the aggregate it becomes reads under the same name.
+ */
+function outerReads(name, options, calls) {
+    const declared = [
+        ...objectProperties(propertyValue(options, 'fields')).map((field) => field.initializer),
+        ...calls.flatMap(({ options: third }) => (third ? [third] : [])),
+    ];
+    return declared.flatMap((field) => {
+        const literal = objectLiteral(field);
+        const computed = literal && propertyValue(literal, 'computed');
+        return computed && ts.isArrowFunction(computed) && identifierText(computed.parameters[0]?.name) !== name
+            ? [computed.body]
+            : [];
+    });
+}
+/** An options literal's text with `option` written first: `{ isId: true, type: String }`. */
+function withOption(literal, option) {
+    return /^\{\s*\}$/.test(literal) ? `{ ${option} }` : literal.replace(/^\{\s*/, `{ ${option}, `);
+}
+/** Whether a field's options are a literal stating no column type, which the class's declaration may say instead. */
+function untyped(options) {
     const literal = objectLiteral(options);
-    if (!literal)
-        return undefined;
-    const text = textOf(literal);
-    return literal.properties.length ? text.replace(/^\{\s*/, '{ isId: true, ') : '{ isId: true }';
+    return !!literal && ['type', 'enum', 'version'].every((option) => propertyValue(literal, option) === undefined);
+}
+/** The constructors the TypeScript types of a class's properties name: `number | null` is `Number`. */
+const DECLARED_TYPES = {
+    number: 'Number',
+    string: 'String',
+    boolean: 'Boolean',
+    bigint: 'BigInt',
+    Date: 'Date',
+};
+/** Each property a class declares as one of {@link DECLARED_TYPES}, with that type's constructor. */
+function declaredTypes(cls) {
+    return new Map(cls.members.filter(ts.isPropertyDeclaration).flatMap((member) => {
+        const key = propertyKey(member.name);
+        const type = member.type;
+        const arms = type && ts.isUnionTypeNode(type) ? type.types : type ? [type] : [];
+        const named = arms.map((arm) => arm.getText()).filter((arm) => arm !== 'null' && arm !== 'undefined');
+        const constructor = named.length === 1 ? DECLARED_TYPES[named[0]] : undefined;
+        return key && constructor ? [[key, constructor]] : [];
+    }));
 }
 /** `author: () => rel.manyToOne(User, { references })` from `{ cardinality: 'm1', entity: () => User, references }`. */
 function relationEntry(key, value, rel) {
@@ -460,7 +520,7 @@ function hookFunction(method, preferred) {
 }
 /**
  * `total: () => rel.items.count()` from a field computed over a relation, `{ computed: (counted) => counted.items.count() }`,
- * which a schema declares among its aggregates; nothing for a field reading no relation, and why where it cannot move.
+ * which a defined entity declares among its aggregates; nothing for a field reading no relation, and why where it cannot move.
  */
 function aggregateEntry(label, key, options, relations, rel) {
     const literal = objectLiteral(options);
@@ -486,7 +546,7 @@ function aggregateEntry(label, key, options, relations, rel) {
 function substituted(body, uses, replacement) {
     return rebased(replacingUses(body, uses, replacement), body);
 }
-/** Notes each property the class typed more narrowly than its schema derives, with the option that keeps it. */
+/** Notes each property the class typed more narrowly than defineEntity derives, with the option that keeps it. */
 function looserTypes(cls, options) {
     const fields = objectLiteral(propertyValue(options, 'fields'));
     return cls.members.flatMap((member) => {
@@ -498,11 +558,11 @@ function looserTypes(cls, options) {
         }
         const written = textOf(declared);
         const said = (option) => propertyValue(field, option) !== undefined;
-        if (/\bJson</.test(written) && !said('shape')) {
+        if (/\bJson</.test(written) && !said('schema')) {
             return [
                 {
                     node: member,
-                    message: `'${key}' was declared ${written}: describe its payload with 'shape' to keep it typed`,
+                    message: `'${key}' was declared ${written}: describe its payload with a Standard Schema, 'f.json(schema)', to keep it typed`,
                 },
             ];
         }

package/dist/definedMessages.d.ts

@@ -0,0 +1,8 @@
+/** Why a name the codemod writes is refused: a file already binds it. */
+export declare const nameClash: (name: string) => string;
+/** Why a defined column's foreign key is refused: no relation joins on it, and none can be written for it. */
+export declare const FOREIGN_KEY_IN_DEFINED = "references another entity, and no relation can be named for it: declare one in '.relations()', as 'rel.manyToOne(Target, { references: (row) => row.key })'";
+/** Why a joined column's `onDelete` is refused: its relation states another, or takes options the codemod cannot write into. */
+export declare const ON_DELETE_ON_RELATION = "joins through a relation that cannot take its 'onDelete': settle the action in that relation's options";
+/** Why a foreign key with no type is refused: a defined column states its own, which only its target's key implied. */
+export declare const NO_KEY_TYPE = "takes its type from its target: write its builder, f.number() and so on, as its key's type";

package/dist/definedMessages.js

@@ -0,0 +1,8 @@
+/** Why a name the codemod writes is refused: a file already binds it. */
+export const nameClash = (name) => `'${name}' is already named here, and the codemod writes it`;
+/** Why a defined column's foreign key is refused: no relation joins on it, and none can be written for it. */
+export const FOREIGN_KEY_IN_DEFINED = "references another entity, and no relation can be named for it: declare one in '.relations()', as 'rel.manyToOne(Target, { references: (row) => row.key })'";
+/** Why a joined column's `onDelete` is refused: its relation states another, or takes options the codemod cannot write into. */
+export const ON_DELETE_ON_RELATION = "joins through a relation that cannot take its 'onDelete': settle the action in that relation's options";
+/** Why a foreign key with no type is refused: a defined column states its own, which only its target's key implied. */
+export const NO_KEY_TYPE = "takes its type from its target: write its builder, f.number() and so on, as its key's type";

package/dist/definedOptions.d.ts

@@ -0,0 +1,6 @@
+/** The options a defined entity's first call keeps, each as it is written there. */
+export declare const FIRST_CALL_OPTIONS: readonly ["name", "table", "schema", "abstract", "extends", "fields"];
+/** The sections a defined entity chains after its first call, in the order it chains them, `relations` last. */
+export declare const CHAINED_OPTIONS: readonly ["computed", "indexes", "checks", "triggers", "filters", "hooks"];
+/** The options a class-form `defineEntity` took that a defined entity keeps as they are, and that incremental definers add to. */
+export declare const KEPT_OPTIONS: readonly ["indexes", "checks", "filters", "triggers"];

package/dist/definedOptions.js

@@ -0,0 +1,6 @@
+/** The options a defined entity's first call keeps, each as it is written there. */
+export const FIRST_CALL_OPTIONS = ['name', 'table', 'schema', 'abstract', 'extends', 'fields'];
+/** The sections a defined entity chains after its first call, in the order it chains them, `relations` last. */
+export const CHAINED_OPTIONS = ['computed', 'indexes', 'checks', 'triggers', 'filters', 'hooks'];
+/** The options a class-form `defineEntity` took that a defined entity keeps as they are, and that incremental definers add to. */
+export const KEPT_OPTIONS = ['indexes', 'checks', 'filters', 'triggers'];

package/dist/definers.d.ts

@@ -20,5 +20,5 @@ export type DefinerCall = {
     readonly options: ts.Expression | undefined;
     readonly rest: readonly ts.Expression[];
 };
-/** `call` read as a class-form definer, or nothing where it is another call, the schema form included. */
+/** `call` read as a class-form definer, or nothing where it is another call, the defined form included. */
 export declare function definerCall(call: ts.CallExpression): DefinerCall | undefined;

package/dist/definers.js

@@ -20,7 +20,7 @@ const KEYED_DEFINERS = new Set([
     'defineHook',
     'defineFilter',
 ]);
-/** `call` read as a class-form definer, or nothing where it is another call, the schema form included. */
+/** `call` read as a class-form definer, or nothing where it is another call, the defined form included. */
 export function definerCall(call) {
     const definer = identifierText(call.expression);
     const [entity, ...rest] = call.arguments;

package/dist/imports.d.ts

@@ -52,6 +52,9 @@ export declare function importRemovalEdits(declaration: ts.ImportDeclaration, el
 export declare function spelledNames(source: ts.SourceFile): ReadonlySet<string>;
 /** The import names in `candidates` that the file no longer spells. */
 export declare function deadImports(elements: readonly ts.ImportSpecifier[], candidates: ReadonlySet<string | undefined>, spelled: ReadonlySet<string>): readonly ts.ImportSpecifier[];
-/** The edits dropping each `uql-orm` import name in `candidates` that the file no longer spells. */
-export declare function unusedImportEdits(source: ts.SourceFile, candidates: ReadonlySet<string>): readonly Edit[];
+/**
+ * The file's `uql-orm` imports with `added` joined to the first, a new import where there is none, and each name in
+ * `candidates` the file no longer spells dropped.
+ */
+export declare function importEdits(source: ts.SourceFile, added: ReadonlySet<string>, candidates: ReadonlySet<string | undefined>): readonly Edit[];
 export {};

package/dist/imports.js

@@ -400,12 +400,30 @@ export function spelledNames(source) {
 export function deadImports(elements, candidates, spelled) {
     return elements.filter((it) => candidates.has(it.name.text) && !spelled.has(it.name.text));
 }
-/** The edits dropping each `uql-orm` import name in `candidates` that the file no longer spells. */
-export function unusedImportEdits(source, candidates) {
+/**
+ * The file's `uql-orm` imports with `added` joined to the first, a new import where there is none, and each name in
+ * `candidates` the file no longer spells dropped.
+ */
+export function importEdits(source, added, candidates) {
+    const declarations = uqlImportDeclarations(source, true);
+    const bound = new Set(declarations.flatMap(({ elements }) => elements.map((it) => it.name.text)));
+    const joined = [...added].filter((name) => !bound.has(name)).toSorted();
+    const [home] = declarations;
+    if (!home) {
+        return joined.length ? [{ start: 0, end: 0, text: `${importText('import', joined, 'uql-orm')}\n` }] : [];
+    }
     const spelled = spelledNames(source);
-    return uqlImportDeclarations(source, true).flatMap(({ declaration, elements }) => {
+    return declarations.flatMap(({ declaration, elements }) => {
         const dead = deadImports(elements, candidates, spelled);
-        return dead.length ? importRemovalEdits(declaration, elements, dead) : [];
+        const join = declaration === home.declaration ? joined : [];
+        const removals = dead.length ? importRemovalEdits(declaration, elements, dead) : [];
+        const first = elements.find((it) => !dead.includes(it));
+        if (!join.length) {
+            return removals;
+        }
+        return first
+            ? [...removals, inserted(first, `${join.join(', ')}, `)]
+            : [replaced(declaration, importText('import', join, 'uql-orm'))];
     });
 }
 /** The import with the `dead` names out and `join` in, nothing else of it touched. */

package/dist/transform.d.ts

@@ -10,17 +10,17 @@ export type FileResult = {
     readonly notes: readonly string[];
 };
 /**
- * Rewrites one file across every breaking change: the earlier ones off the checker, then column builders and schema
+ * Rewrites one file across every breaking change: the earlier ones off the checker, then column builders and defineEntity
  * chains off the text those produced, so neither pass edits what the other writes.
  */
 export declare function transformFile(source: ts.SourceFile, checker: ts.TypeChecker, options?: {
     readonly strictNullChecks: boolean;
 }): FileResult;
 /**
- * The rewrites the checker reads types for, up to the schema entities a class-form registration declares. The
+ * The rewrites the checker reads types for, up to the defined entities a class-form registration declares. The
  * builder's and querier's methods are known by name, so they are read only in a file importing uql-orm, and `expr`
  * only where it is uql's.
  */
 export declare function rewriteLegacy(source: ts.SourceFile, checker: ts.TypeChecker, options: {
     readonly strictNullChecks: boolean;
-}): FileResult & Pass;
+}, taken?: ReadonlySet<string>): FileResult & Pass;

package/dist/transform.js

@@ -3,6 +3,8 @@ import { BUILDER_NAMES, isBuilder, toBuilders } from './builders.js';
 import { foldClassDecorators } from './classOptions.js';
 import { rewriteColumnRefs } from './columnRefs.js';
 import { createContext, instanceTypeOf, locationAt, memberNames, ownerOf, } from './context.js';
+import { toDefinedEntities } from './definedEntity.js';
+import { nameClash } from './definedMessages.js';
 import { definerCall } from './definers.js';
 import { appended, editedText, followed, inserted, original, replaced, unedited, } from './edits.js';
 import { columnExpressions, handNamedColumns, sqlTag, sqlWhereEdit, templateOf } from './entitySql.js';
@@ -11,7 +13,6 @@ import { rewriteBuilderIndexLengths, rewriteJsonIndexEntries } from './jsonIndex
 import { entityGetterTarget, fieldKeysEdits, isCallback, keyListEdits, mappedByEdits, memberAccess, paramFor, quoted, referencesEdits, } from './keyMaps.js';
 import { toMigrationBuilders } from './migrationBuilders.js';
 import { relationTargetFor } from './relationTarget.js';
-import { toSchemaEntities } from './schemaEntity.js';
 import { statementTemplate } from './statementSql.js';
 import { arrayElements, decoratorName, decoratorsOf, FIELD_DECORATORS, identifierText, indentOf, namedProperty, objectLiteral, objectProperties, optionsOf, propertyKey, propertyValue, } from './syntax.js';
 const RELATION_DECORATORS = new Set(['OneToOne', 'ManyToOne', 'OneToMany', 'ManyToMany']);
@@ -681,13 +682,13 @@ function rewriteRawCall(node, ctx) {
     }
 }
 /**
- * Rewrites one file across every breaking change: the earlier ones off the checker, then column builders and schema
+ * Rewrites one file across every breaking change: the earlier ones off the checker, then column builders and defineEntity
  * chains off the text those produced, so neither pass edits what the other writes.
  */
 export function transformFile(source, checker, options = { strictNullChecks: true }) {
-    const legacy = rewriteLegacy(source, checker, options);
-    const located = (pass) => (at) => locationAt(source, pass.sourceOffset(at));
     const taken = foreignNames(source, BUILDER_NAMES, checker);
+    const legacy = rewriteLegacy(source, checker, options, taken);
+    const located = (pass) => (at) => locationAt(source, pass.sourceOffset(at));
     const builders = toBuilders(source.fileName, legacy.text, { locate: located(legacy), taken });
     const { text, unresolved } = toMigrationBuilders(source.fileName, builders.text, located(followed(legacy, builders)));
     return {
@@ -699,11 +700,11 @@ export function transformFile(source, checker, options = { strictNullChecks: tru
     };
 }
 /**
- * The rewrites the checker reads types for, up to the schema entities a class-form registration declares. The
+ * The rewrites the checker reads types for, up to the defined entities a class-form registration declares. The
  * builder's and querier's methods are known by name, so they are read only in a file importing uql-orm, and `expr`
  * only where it is uql's.
  */
-export function rewriteLegacy(source, checker, options) {
+export function rewriteLegacy(source, checker, options, taken = foreignNames(source, BUILDER_NAMES, checker)) {
     const ctx = createContext(source, checker, options.strictNullChecks);
     const importsUql = uqlImportDeclarations(source, true).length > 0;
     const importsExpr = uqlImport(source, 'expr', true) !== undefined;
@@ -743,17 +744,20 @@ export function rewriteLegacy(source, checker, options) {
     visit(source);
     const clash = clashingName(ctx);
     if (clash) {
-        ctx.report(clash, `'${clash.text}' is already named here, and the codemod writes it: rename that, then run again`);
+        ctx.report(clash, `${nameClash(clash.text)}: rename that, then run again`);
         return { ...fileResult(ctx, source.getFullText()), ...unedited(source.getFullText()) };
     }
     const dead = new Set([...deadImportNames(ctx), ...rewriteColumnRefs(ctx)]);
     rewriteImports(dead, ctx);
     reportRemovedExports(ctx);
     const edited = editedText(source.getFullText(), ctx.edits);
-    const schema = toSchemaEntities(source.fileName, edited.text, (at) => locationAt(source, edited.sourceOffset(at)));
-    ctx.unresolved.push(...schema.unresolved);
-    ctx.notes.push(...schema.notes);
-    return { ...fileResult(ctx, schema.text), sourceOffset: followed(edited, schema).sourceOffset };
+    const defined = toDefinedEntities(source.fileName, edited.text, {
+        locate: (at) => locationAt(source, edited.sourceOffset(at)),
+        taken,
+    });
+    ctx.unresolved.push(...defined.unresolved);
+    ctx.notes.push(...defined.notes);
+    return { ...fileResult(ctx, defined.text), sourceOffset: followed(edited, defined).sourceOffset };
 }
 function fileResult({ source, unresolved, notes }, text) {
     return { fileName: source.fileName, text, changed: text !== source.getFullText(), unresolved, notes };

package/package.json

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

package/dist/schemaEntity.d.ts

@@ -1,12 +0,0 @@
-import { type Pass } from './edits.js';
-export type SchemaResult = Pass & {
-    readonly unresolved: string[];
-    readonly notes: string[];
-};
-/**
- * Declares each class `defineEntity(Class, options)` registered as the schema `defineEntity({ name, ... })`,
- * folding the string-keyed definers of the same class in. Read off the text the other rewrites produced,
- * whose options already name members by callback, so it only moves what is written. An entity it cannot
- * declare faithfully is left as written and reported.
- */
-export declare function toSchemaEntities(fileName: string, text: string, locate?: (at: number) => string): SchemaResult;

package/dist/schemaOptions.d.ts

@@ -1,6 +0,0 @@
-/** The options a schema's first call keeps, each as it is written there. */
-export declare const FIRST_CALL_OPTIONS: readonly ["name", "table", "schema", "abstract", "extends", "fields"];
-/** The sections a schema chains after its first call, in the order it chains them, `relations` last. */
-export declare const CHAINED_OPTIONS: readonly ["computed", "indexes", "checks", "triggers", "filters", "hooks"];
-/** The options a class-form `defineEntity` took that a schema keeps as they are, and that incremental definers add to. */
-export declare const KEPT_OPTIONS: readonly ["indexes", "checks", "filters", "triggers"];

package/dist/schemaOptions.js

@@ -1,6 +0,0 @@
-/** The options a schema's first call keeps, each as it is written there. */
-export const FIRST_CALL_OPTIONS = ['name', 'table', 'schema', 'abstract', 'extends', 'fields'];
-/** The sections a schema chains after its first call, in the order it chains them, `relations` last. */
-export const CHAINED_OPTIONS = ['computed', 'indexes', 'checks', 'triggers', 'filters', 'hooks'];
-/** The options a class-form `defineEntity` took that a schema keeps as they are, and that incremental definers add to. */
-export const KEPT_OPTIONS = ['indexes', 'checks', 'filters', 'triggers'];