uql-codemod

Rewrites a uql-orm project across the breaking changes that can be made mechanically. Dry run first:

npx uql-codemod --dry-run
npx uql-codemod

| Flag | | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | --project=<path> | The tsconfig.json to read, ./tsconfig.json by default. It has to cover your entities: the type checker is what says each property's type. | | --dry-run | Report what would change and touch nothing. | | --include=<a,b> | Only files whose path contains one of these fragments. |

Only --flag=value is read, and anything unrecognised is an error. It exits 0 when nothing is left for you, 1 when something is, and 2 when it could not start. Edits are spliced into the text, so everything it does not touch stays byte for byte as written.

What it rewrites

• type on a @Field/@Id that has none, from the property's declared type; not beside references, whose column comes from the key it points at.
• entity: () => X on a bare relation decorator, and Relation<T> to T, its import going with the last use.
• virtual to computed (on @Field and in defineEntity's fields), a check's expression and a filter's condition to where (@Entity/defineEntity, @Filter, defineFilter), raw('sql') to the tagged template, and a raw alias argument onto .as().
• Members named by string to callbacks: mappedBy: 'author' to (post) => post.author, and @Index, include, references and @Entity/defineEntity's indexes and hooks likewise: @Index((post) => [post.title]).
• references: (post) => post.authorId on a to-one (@ManyToOne, @OneToOne, or defineEntity/defineRelation) that names no foreign key, declaring @Field({ references: () => User }) authorId first on a decorated class that has no such column, typed as the key it points at.
• A partial-index where string to raw, importing it, on entities and in the migration builder.
• col('cost') to the ref it names, (product) => raw`${product.cost}` in a computed and refs(Item).cost in a statement, and $lock: { wait: 'skip' } to { $wait: 'skip' }, or to true for {} and a 'block' wait.
• An aggregate's $agg to $select, and each field it or $text's $fields names to a key: { $sum: { amount: true } }.
• Renamed exports, at the import and every use: QueryWhereMap to QueryWhere, 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, 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.
• import 'reflect-metadata', and experimentalDecorators/emitDecoratorMetadata in tsconfig.json, comments and formatting kept.

What it leaves to you

Reported with what to do, never guessed:

• target: esnext, the one target that leaves decorators untransformed, and a value inherited through extends.
• @Log(), @Serialized(), @Transactional() and @InjectQuerier(): a @Transactional() method becomes a pool.transaction() around its body, and only you know which pool.
• An export removed with no one-to-one replacement (setQuerierPool, getQuerier, augmentWhere, AbstractPgQuerier, ...), an internal the root no longer exports (AbstractSqlQuerier, fieldOf, ...), the migration storages, and any import from uql-orm/util the root does not export (raw, refs, ... move to uql-orm).
• A value it cannot read: options passed as a variable or a spread, a list that is not a literal, a key under a computed name.
• A to-one onto a composite key: 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, a defineEntity whose fields leave it out, or a defineRelation whose entity has no such member.
• A partial-index where string that interpolates, since raw would bind what the template spliced in.
• A col() whose entity it cannot tell: a raw built apart from its query, one under a relation filter, or a column no field maps.
• SQL in a definition that names a column by hand, as a note: a rename reaches a callback's refs, (user) => raw`lower(${user.email})` , and never the text.
• A property whose type maps to no column (Json<T>, a vector, a mixed union).
• A branded string id, written as type: String to keep the column you have, with a note: 'uuid' is a native column, and a migration.

After it runs

tsc is the rest of the migration: what the codemod wrote is checked against the property it describes, so anything it got wrong is a compile error. See the upgrade guide.

Why TypeScript 6

Reading each property's type needs the checker, so TypeScript is a runtime dependency. 7's entry point exports no compiler API yet and has no standalone parser, which the tsconfig.json rewrite needs to keep your formatting; revisit once that API is stable.

License

MIT