uql-codemod 0.50.0 → 0.51.0

package/README.md

@@ -25,18 +25,19 @@ 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, and its `aggregates` to `.relations()`' second callback. A schema 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 a schema, goes 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, whole or not at all: `export const Post = defineEntity({ name: 'Post', fields })` with its sections chained, as a schema'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 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 an aggregate 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`.
 - An aggregate's `$agg` to `$select`, and each field it or `$text`'s `$fields` names to a key: `{ $sum: { amount: true } }`.
-- Renamed exports, at the import and every use: `raw` to `sql`, `QueryWhereMap` to `QueryWhere`, `IndexColumnSchema` to `IndexEntry`, `IndexColumnModifiers` to `IndexEntryModifiers`, `RelationKeyMap` to `KeyMap`, `FilterCondition` to `FilterWhere`, `SqlMigrationModuleOptions` to `MigrationModuleOptions`, `buildSqlQuerierMigrationModule` to `buildMigrationModule`, `QueryDialect` to `SqlQueryDialect`, `EngineFeatures` to `DialectFeatures`, `KnownMigratorDialect` to `DialectName`, `D1Preparer`/`D1Database` to `D1Queryable`, and the removed driver classes to the one each extended: `PgDialect`/`NeonDialect`/`PgliteDialect` to `PostgresDialect`, `CrdbQuerier`/`NeonQuerier` to `PgQuerier`, `LibsqlQuerier`/`TursoQuerier` to `HranaQuerier`, `TursoLocalQuerier` to `SqliteQuerier` and `TursoDatabase` to `SqliteDatabase`, `MySql2Dialect` to `MySqlDialect`, `MongodbNativeDialect` to `MongoDialect`, `Sqlite3QuerierPool` to `SqliteQuerierPool`, the migration builder's `I`-prefixed types to the unprefixed name (`IColumnBuilder`/`IColumnFactory`, and `uql-orm/migrate`'s `ColumnBuilder`/`ColumnFactory`, to `TableColumnBuilder`/`TableColumnFactory`), moving the import to the entry that exports it; and `MongoQuerier`, `isMongoQuerier` and `MongoSchemaIntrospector` to `uql-orm/mongodb`.
+- An upsert's conflict keys to a query, `upsertOne(User, { email: true }, row)` to `upsertOne(User, { $conflict: { email: true } }, row)`, and its `{ update: X }` options to `X` as its fourth argument, in `upsertOne`, `upsertMany` and a trigger's `upsertInto`; `const { id } = await upsertOne(...)` to `const id`.
+- Renamed exports, at the import and every use: `raw` to `sql`, `QueryWhereMap` to `QueryWhere`, `IndexColumnSchema` to `IndexEntry`, `IndexColumnModifiers` to `IndexEntryModifiers`, `RelationKeyMap` to `KeyMap`, `FilterCondition` to `FilterWhere`, `SqlMigrationModuleOptions` to `MigrationModuleOptions`, `buildSqlQuerierMigrationModule` to `buildMigrationModule`, `QueryDialect` to `SqlQueryDialect`, `EngineFeatures` to `DialectFeatures`, `KnownMigratorDialect` to `DialectName`, `QueryConflictPaths` to `QueryConflictKeys`, `D1Preparer`/`D1Database` to `D1Queryable`, and the removed driver classes to the one each extended: `PgDialect`/`NeonDialect`/`PgliteDialect` to `PostgresDialect`, `CrdbQuerier`/`NeonQuerier` to `PgQuerier`, `LibsqlQuerier`/`TursoQuerier` to `HranaQuerier`, `TursoLocalQuerier` to `SqliteQuerier` and `TursoDatabase` to `SqliteDatabase`, `MySql2Dialect` to `MySqlDialect`, `MongodbNativeDialect` to `MongoDialect`, `Sqlite3QuerierPool` to `SqliteQuerierPool`, the migration builder's `I`-prefixed types to the unprefixed name (`IColumnBuilder`/`IColumnFactory`, and `uql-orm/migrate`'s `ColumnBuilder`/`ColumnFactory`, to `TableColumnBuilder`/`TableColumnFactory`), moving the import to the entry that exports it; and `MongoQuerier`, `isMongoQuerier` and `MongoSchemaIntrospector` to `uql-orm/mongodb`.
 - Imports off `uql-orm/maria`, `uql-orm/mongo` and `uql-orm/bunSql` to `uql-orm/mariadb`, `uql-orm/mongodb` and `uql-orm/bun-sql`, and off `uql-orm/type`, `uql-orm/dialect`, `uql-orm/entity`, `uql-orm/querier` and `uql-orm/namingStrategy` to `uql-orm`.
 - The `[idKey]?: '...'` brand, and its import, on a key not called `id`, `_id` or `uuid` and on every composite.
 
@@ -51,10 +52,10 @@ 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, 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 schema 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 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 a Standard Schema, 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.

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.
  */
@@ -17,10 +17,10 @@ export declare function toBuilders(fileName: string, text: string, { locate, tak
     readonly taken: ReadonlySet<string>;
 }): BuildersResult;
 /**
- * A schema's statement, `const X = defineEntity({...})`, its call written as a chain and the builders it writes, or why
+ * 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 chainedSchema(text: string): {
+export declare function chainedEntity(text: string): {
     readonly text: string;
     readonly builders: ReadonlySet<string>;
 } | {

package/dist/builders.js

@@ -1,11 +1,11 @@
 import ts from 'typescript';
 import { call, flag, flagOrCall } from './columnMethods.js';
 import { formatFindings, locationAt } from './context.js';
+import { UNJOINED_FOREIGN_KEY, 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 { FOREIGN_KEY_IN_SCHEMA, NO_KEY_TYPE, nameClash, ON_DELETE_ON_RELATION } from './schemaMessages.js';
-import { CHAINED_OPTIONS, FIRST_CALL_OPTIONS } from './schemaOptions.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 = {
@@ -232,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,
@@ -242,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({
@@ -263,7 +263,7 @@ function schemaEdits(call, findings, used) {
     const aggregates = propertyValue(options, 'aggregates');
     const read = fields.properties.map((prop) => ({
         prop,
-        column: ts.isPropertyAssignment(prop) ? schemaColumn(prop.initializer) : undefined,
+        column: ts.isPropertyAssignment(prop) ? definedColumn(prop.initializer) : undefined,
     }));
     const { joins, inferred } = joinsOf(relations, targetsOf(read), param);
     const targets = {
@@ -324,14 +324,14 @@ function schemaEdits(call, findings, used) {
         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's builder off its options or chain, its `references` and `onDelete` taken out to move to a relation. */
-function schemaColumn(node) {
+/** 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');
@@ -340,7 +340,7 @@ function schemaColumn(node) {
         }
         const target = targetOf(references.call.arguments[0]);
         if (identifierText(references.receiver) === 'f' || !target) {
-            return { message: target ? NO_KEY_TYPE : FOREIGN_KEY_IN_SCHEMA };
+            return { message: target ? NO_KEY_TYPE : UNJOINED_FOREIGN_KEY };
         }
         const onDelete = methods.get('onDelete');
         const cut = [references, ...(onDelete ? [onDelete] : [])].map((method) => ({
@@ -360,7 +360,7 @@ function schemaColumn(node) {
     const references = options.get('references');
     const target = references && targetOf(references);
     if (references && !target) {
-        return { message: FOREIGN_KEY_IN_SCHEMA };
+        return { message: UNJOINED_FOREIGN_KEY };
     }
     if (target && !options.has('type')) {
         return { message: NO_KEY_TYPE };
@@ -381,7 +381,7 @@ function targetOf(getter) {
 function targetsOf(read) {
     return new Map(read.flatMap(({ prop, column }) => column && 'key' in column && column.key ? [[prop.name?.getText(), column.key.target]] : []));
 }
-/** The schema's columns' foreign keys claimed in turn, the problem of each column by its name node. */
+/** 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 }) => {
@@ -408,7 +408,7 @@ function claimKey(name, { target, onDelete }, claims, targets) {
     }
     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_SCHEMA };
+        return { claims, problem: UNJOINED_FOREIGN_KEY };
     }
     const written = [
         `references: (${targets.param}) => ${targets.param}.${key}`,
@@ -437,7 +437,7 @@ function movedOnDelete(relation, onDelete, claims) {
         ? { claims }
         : { claims: { ...claims, options: new Map(claims.options).set(relation, [...current, written]) } };
 }
-/** The relation calls a schema's `relations` returns, one per relation. */
+/** 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;
@@ -543,8 +543,8 @@ function appendedEntries(literal, entries, base) {
     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. */
@@ -680,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) => {
@@ -714,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.
  */
@@ -734,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;
             }
         }
@@ -761,17 +761,17 @@ export function toBuilders(fileName, text, { locate, taken }) {
     };
 }
 /**
- * A schema's statement, `const X = defineEntity({...})`, its call written as a chain and the builders it writes, or why
+ * 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 chainedSchema(text) {
-    const source = ts.createSourceFile('/schema.ts', text, ts.ScriptTarget.Latest, true);
+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(...schemaEdits(node, findings, used));
+            edits.push(...definedEdits(node, findings, used));
             return;
         }
         ts.forEachChild(node, visit);

package/dist/{schemaEntity.d.ts → definedEntity.d.ts}

@@ -1,15 +1,15 @@
 import { type Pass } from './edits.js';
-export type SchemaResult = Pass & {
+export type DefinedResult = Pass & {
     readonly unresolved: string[];
     readonly notes: string[];
 };
 /**
- * Declares each class `defineEntity(Class, options)` registered as the schema `defineEntity({ name, fields })` and its
+ * 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 toSchemaEntities(fileName: string, text: string, { locate, taken }: {
+export declare function toDefinedEntities(fileName: string, text: string, { locate, taken }: {
     readonly locate?: (at: number) => string;
     readonly taken: ReadonlySet<string>;
-}): SchemaResult;
+}): DefinedResult;

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

@@ -1,14 +1,14 @@
 import ts from 'typescript';
-import { chainedSchema } from './builders.js';
+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 { importEdits } from './imports.js';
 import { memberKey, paramFor, quoted } from './keyMaps.js';
-import { nameClash } from './schemaMessages.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',
@@ -49,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, fields })` and its
+ * 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, taken }) {
+export function toDefinedEntities(fileName, text, { locate, taken }) {
     if (!CLASS_FORM_CALL.test(text)) {
         return { ...unedited(text), unresolved: [], notes: [] };
     }
@@ -82,12 +82,12 @@ export function toSchemaEntities(fileName, text, { locate, taken }) {
             });
             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;
         }
-        const chained = chainedSchema(schema.text);
+        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;
@@ -99,7 +99,7 @@ export function toSchemaEntities(fileName, text, { locate, taken }) {
         }
         for (const builder of chained.builders)
             written.add(builder);
-        notes.push(...schema.notes);
+        notes.push(...defined.notes);
         edits.push(removeStatement(cls));
         for (const { call } of calls) {
             edits.push(call === entityCall ? replaced(call.parent, indented(chained.text, call.parent)) : removeStatement(call.parent));
@@ -113,7 +113,7 @@ export function toSchemaEntities(fileName, text, { locate, taken }) {
         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'));
@@ -140,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)) });
@@ -155,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))) {
@@ -165,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);
@@ -421,7 +421,7 @@ 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;
@@ -520,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);
@@ -546,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) => {

package/dist/{schemaMessages.d.ts → definedMessages.d.ts}

@@ -1,8 +1,8 @@
 /** Why a name the codemod writes is refused: a file already binds it. */
 export declare const nameClash: (name: string) => string;
-/** Why a schema column's foreign key is refused: no relation joins on it, and none can be written for it. */
-export declare const FOREIGN_KEY_IN_SCHEMA = "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 defined column's foreign key is refused: no relation joins on it, and none can be written for it. */
+export declare const UNJOINED_FOREIGN_KEY = "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 schema column states its own, which only its target's key implied. */
+/** 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/{schemaMessages.js → definedMessages.js}

@@ -1,8 +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 schema column's foreign key is refused: no relation joins on it, and none can be written for it. */
-export const FOREIGN_KEY_IN_SCHEMA = "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 defined column's foreign key is refused: no relation joins on it, and none can be written for it. */
+export const UNJOINED_FOREIGN_KEY = "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 schema column states its own, which only its target's key implied. */
+/** 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.js

@@ -76,6 +76,7 @@ export const SQL_TAG = 'sql';
  */
 const RENAMED_EXPORTS = new Map([
     ['QueryWhereMap', { to: 'QueryWhere' }],
+    ['QueryConflictPaths', { to: 'QueryConflictKeys' }],
     ['IndexColumnSchema', { to: 'IndexEntry' }],
     ['IndexColumnModifiers', { to: 'IndexEntryModifiers' }],
     ['RelationKeyMap', { to: 'KeyMap' }],

package/dist/transform.d.ts

@@ -10,14 +10,14 @@ 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.
  */

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,8 +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 { nameClash } from './schemaMessages.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']);
@@ -428,19 +428,31 @@ function rewriteBuilderCall(call, ctx) {
 }
 const UPSERT_CALLS = new Set(['upsertOne', 'upsertMany', 'upsertInto']);
 /**
- * Rewrites an upsert's options holding `update` alone into that update, its fourth argument now. Read wherever it is
- * called, since a querier is seldom imported from uql where it is used. Any other fourth argument is already an
- * update, `{}` included, so a second run changes nothing.
+ * Rewrites an upsert's conflict keys into its query's `$conflict`, `{ $conflict: { sku: true } }`, and its options
+ * holding `update` alone into that update, its fourth argument now. Read wherever it is called, since a querier is
+ * seldom imported from uql where it is used. A query already naming `$conflict`, or typed with one, is left as it is,
+ * and any other fourth argument is already an update, `{}` included, so a second run changes nothing.
  */
 function rewriteUpsertCall(call, ctx) {
     const callee = call.expression;
     const name = identifierText(ts.isPropertyAccessExpression(callee) ? callee.name : callee);
+    if (!name || !UPSERT_CALLS.has(name)) {
+        return;
+    }
+    const keys = call.arguments[1];
+    if (call.arguments.length >= 3 && keys && isConflictKeys(keys, ctx)) {
+        ctx.edits.push(replaced(keys, ['{ $conflict: ', original(keys), ' }']));
+    }
     const options = call.arguments[3];
     const update = options && upsertUpdate(options);
-    if (name && UPSERT_CALLS.has(name) && update) {
+    if (update) {
         ctx.edits.push(replaced(options, [original(update)]));
     }
 }
+/** Whether `keys` is the old conflict map, `{ sku: true }`: an argument of its own, not yet a query naming `$conflict`. */
+function isConflictKeys(keys, ctx) {
+    return !ts.isSpreadElement(keys) && !ctx.checker.getTypeAtLocation(keys).getProperty('$conflict');
+}
 /** The value of options holding `update` alone, `{ update: value }` or `{ update }`. */
 function upsertUpdate(options) {
     const literal = objectLiteral(options);
@@ -682,7 +694,7 @@ 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 }) {
@@ -700,7 +712,7 @@ 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.
  */
@@ -751,13 +763,13 @@ export function rewriteLegacy(source, checker, options, taken = foreignNames(sou
     rewriteImports(dead, ctx);
     reportRemovedExports(ctx);
     const edited = editedText(source.getFullText(), ctx.edits);
-    const schema = toSchemaEntities(source.fileName, edited.text, {
+    const defined = toDefinedEntities(source.fileName, edited.text, {
         locate: (at) => locationAt(source, edited.sourceOffset(at)),
         taken,
     });
-    ctx.unresolved.push(...schema.unresolved);
-    ctx.notes.push(...schema.notes);
-    return { ...fileResult(ctx, schema.text), sourceOffset: followed(edited, schema).sourceOffset };
+    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.50.0",
+  "version": "0.51.0",
   "type": "module",
   "engines": {
     "node": ">=22.18"

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'];