uql-orm 0.42.1 → 0.44.0

package/dist/entity/decorator/members.d.ts

@@ -1,4 +1,5 @@
 import type { EntityGetter, FieldOptions, FieldType, IdValue, RelationManyToManyOptions, RelationManyToOneOptions, RelationOneToManyOptions, RelationOneToOneOptions, TsTypeOf } from '../../type/index.js';
+import type { RejectIncompatible } from '../../util/index.js';
 /** A member decorator that also constrains the property it may be applied to. */
 type MemberDecorator<V> = (value: undefined, context: ClassFieldDecoratorContext<unknown, V>) => void;
 /**
@@ -51,7 +52,7 @@ export declare function Field<O extends FieldOptions<DeclaredValue<O>> & ({
     type: FieldType;
 } | {
     references: EntityGetter;
-}) & RejectUnknown<O, FieldOptions>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
+}) & RejectUnknown<O, FieldOptions> & RejectIncompatible<O>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
 /**
  * Declares the primary key, checked the same way as `@Field`.
  *
@@ -60,7 +61,9 @@ export declare function Field<O extends FieldOptions<DeclaredValue<O>> & ({
  */
 export declare function Id<O extends FieldOptions<DeclaredValue<O>> & {
     type: FieldType;
-} & RejectUnknown<O, FieldOptions>>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
+} & RejectUnknown<O, FieldOptions> & RejectIncompatible<O> & {
+    readonly nullable?: false;
+}>(opts: O): MemberDecorator<DeclaredValue<O> | undefined>;
 /**
  * `E` comes from the mandatory `entity` getter, so the context can insist the property really holds that
  * entity: `@ManyToOne({ entity: () => Other })` on a `Company` field stops compiling, and a to-many

package/dist/entity/index.d.ts

@@ -1,3 +1,3 @@
 export * from './decorator/entity.js';
 export * from './decorator/members.js';
-export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, assertSoleId, idOf, soleIdOf, } from './metadata/definition.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, idOf, soleIdOf, } from './metadata/definition.js';

package/dist/entity/index.js

@@ -1,3 +1,3 @@
 export * from './decorator/entity.js';
 export * from './decorator/members.js';
-export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, assertSoleId, idOf, soleIdOf, } from './metadata/definition.js';
+export { defineEntity, defineField, defineFilter, defineHook, defineId, defineIndex, defineRelation, getEntities, getMeta, removeEntity, assertSoleId, idOf, soleIdOf, } from './metadata/definition.js';

package/dist/entity/metadata/definition.d.ts

@@ -1,4 +1,4 @@
-import type { EntityId, EntityIndexInput, EntityMeta, EntityOptions, FieldKey, FieldOptions, FilterOptions, HookEvent, IdKey, RelationOptions, Type } from '../../type/index.js';
+import type { EntityId, EntityIndexInput, EntityMembers, EntityMeta, EntityOptions, FieldKey, FieldOptions, FilterOptions, HookEvent, IdKey, RelationOptions, Type } from '../../type/index.js';
 export declare function defineField<E>(entity: Type<E>, key: string, opts?: FieldOptions): EntityMeta<E>;
 export declare function defineId<E>(entity: Type<E>, key: string, opts: FieldOptions): EntityMeta<E>;
 export declare function defineRelation<E>(entity: Type<E>, key: string, opts: RelationOptions): EntityMeta<E>;
@@ -9,21 +9,17 @@ export declare function defineHook<E>(entity: Type<E>, methodName: string, event
  */
 export declare function defineIndex<E>(entity: Type<E>, index: EntityIndexInput<FieldKey<E>, E>): EntityMeta<E>;
 export declare function defineFilter<E>(entity: Type<E>, name: string, opts: FilterOptions<E>): EntityMeta<E>;
-/**
- * What a decorator bag and {@link EntityOptions} have in common at registration time. The keyed mapped
- * types in `EntityOptions<E>` are what check the imperative call; a member decorator has no class to key
- * against, so by the time either reaches the primitives the keys are plain strings.
- */
-type MemberSpecs = {
-    readonly fields?: Readonly<Record<string, FieldOptions | undefined>>;
-    readonly relations?: Readonly<Record<string, RelationOptions | undefined>>;
-    readonly hooks?: Readonly<Partial<Record<HookEvent, readonly string[]>>>;
-};
 /**
  * Feeds fields, relations and hooks into the `define*` primitives, so the decorators and the imperative
  * API converge on one registration path before anything is finalized.
  */
-export declare function applyMembers<E>(entity: Type<E>, specs: MemberSpecs | undefined): void;
+export declare function applyMembers<E>(entity: Type<E>, specs: EntityMembers | undefined): void;
+/**
+ * Registers an entity described by data alone, minting the class the registry keys it by. The row
+ * type follows from the spec - see {@link SpecRow} - so a definition written out is checked column by
+ * column, and one assembled at runtime is the column bag it is. Pass `Row` to name a shape the spec
+ * cannot describe, such as the interface `uql-migrate types` generated for it.
+ */
 export declare function defineEntity<E>(entity: Type<E>, opts?: EntityOptions<E>): EntityMeta<E>;
 /**
  * Refuses an entity whose primary key is not one column, naming the path that cannot express it.
@@ -42,6 +38,12 @@ export declare function soleIdOf<E>(meta: EntityMeta<E>, what: string): IdKey<E>
  * one of its columns would address every row agreeing on that one.
  */
 export declare function idOf<E>(meta: EntityMeta<E>, row: E): EntityId<E>;
+/**
+ * Forgets an entity, and reports whether there was one - for a registry that grows at runtime, where a
+ * deleted content type would otherwise keep its metadata for the life of the process. Nothing rewrites
+ * what pointed at it, and a decorated class does not come back (its decorators drained at first
+ * registration). See the Runtime Schemas guide.
+ */
+export declare function removeEntity<E>(entity: Type<E>): boolean;
 export declare function getEntities(): Type<unknown>[];
 export declare function getMeta<E>(entity: Type<E>): EntityMeta<E>;
-export {};

package/dist/entity/metadata/definition.js

@@ -1,20 +1,29 @@
 import { SOFT_DELETE_FILTER } from '../../type/index.js';
-import { getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, } from '../../util/index.js';
+import { entityName, fieldOptionConflict, getKeys, ddlText, hasKeys, isToManyRelation, lowerFirst, normalizeIndexColumn, upperFirst, } from '../../util/index.js';
 import { ownRegistrations } from '../decorator/bag.js';
-// Held on `globalThis` via the global symbol registry so a single metadata map survives multiple
-// evaluations of this module (HMR, duplicated/federated bundles, ESM+CJS dual-loading). Version-suffixed
-// because v1 changed the `FieldOptions` shape: a tree holding both majors gets two maps rather than one
-// map with entries the other major cannot read.
-const holder = globalThis;
-const metaKey = Symbol.for('uql-orm/entity/metadata/v1');
-const metas = holder[metaKey] ?? new Map();
-holder[metaKey] = metas;
+/**
+ * A map held on `globalThis` through the global symbol registry, so a single one survives multiple
+ * evaluations of this module (HMR, duplicated/federated bundles, ESM+CJS dual-loading). The keys are
+ * version-suffixed because v1 changed the `FieldOptions` shape: a tree holding both majors gets two
+ * maps rather than one map with entries the other major cannot read.
+ */
+function globalMap(key) {
+    const holder = globalThis;
+    const symbol = Symbol.for(key);
+    holder[symbol] ??= new Map();
+    return holder[symbol];
+}
+const metas = globalMap('uql-orm/entity/metadata/v1');
 export function defineField(entity, key, opts = {}) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (!opts.type && !opts.references && !opts.virtual) {
         throw new TypeError(`'${entity.name}.${key}' needs a 'type'. Declare it - '@Field({ type: String })' - or point the field ` +
             "at another entity with 'references', which resolves the column type from its primary key.");
     }
+    const conflict = fieldOptionConflict(opts);
+    if (conflict) {
+        throw new TypeError(`'${entity.name}.${key}' ${conflict}.`);
+    }
     const fieldKey = key;
     // Flagged when the author gave `references` but no `type`, so schema generation knows to resolve the
     // column from the referenced primary key (picking up its `columnType`, length and chained keys)
@@ -32,7 +41,7 @@ export function defineRelation(entity, key, opts) {
     if (!opts.entity) {
         throw new TypeError(`'${entity.name}.${key}' needs an 'entity' getter, e.g. '@ManyToOne({ entity: () => Company })'.`);
     }
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     // Registration writes the authored shape into a map declared as resolved: `getMeta` runs
     // `fillRelations`, which settles `entity`, `references` and `mappedBy` or throws. Bridging the two
     // shapes here is what lets every consumer read `RelationMeta` without asserting.
@@ -41,7 +50,7 @@ export function defineRelation(entity, key, opts) {
     return meta;
 }
 export function defineHook(entity, methodName, event) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (!meta.hooks)
         meta.hooks = {};
     if (!meta.hooks[event])
@@ -54,7 +63,7 @@ export function defineHook(entity, methodName, event) {
  * lets the dialects render one shape instead of re-parsing it.
  */
 export function defineIndex(entity, index) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (!meta.indexes)
         meta.indexes = [];
     meta.indexes.push({
@@ -66,7 +75,7 @@ export function defineIndex(entity, index) {
     return meta;
 }
 export function defineFilter(entity, name, opts) {
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     if (name === SOFT_DELETE_FILTER) {
         throw TypeError(`'${entity.name}' filter name '${SOFT_DELETE_FILTER}' is reserved; it is auto-registered from @Field({ softDelete })`);
     }
@@ -103,6 +112,12 @@ export function applyMembers(entity, specs) {
         }
     }
 }
+/**
+ * Registers an entity described by data alone, minting the class the registry keys it by. The row
+ * type follows from the spec - see {@link SpecRow} - so a definition written out is checked column by
+ * column, and one assembled at runtime is the column bag it is. Pass `Row` to name a shape the spec
+ * cannot describe, such as the interface `uql-migrate types` generated for it.
+ */
 export function defineEntity(entity, opts = {}) {
     // Ahead of any registration, so a rejected definition leaves nothing half-written in the registry.
     // A dotted name reads like a schema and is not one: it escapes as a single identifier, so the
@@ -112,7 +127,7 @@ export function defineEntity(entity, opts = {}) {
         throw new TypeError(`'${entity.name}' has a dotted name '${opts.name}'. Name the schema separately as ` +
             `{ schema: '${schema}', name: '${rest.join('.')}' }.`);
     }
-    const meta = ensureMeta(entity);
+    const meta = ensureWritableMeta(entity);
     // Covers `defineEntity(Decorated)` called on a class whose members carry decorators. `@Entity()`
     // drains `context.metadata` itself, because TypeScript only attaches `Symbol.metadata` to the class
     // after class decorators return; draining empties the bag, so whichever runs second is a no-op.
@@ -125,15 +140,27 @@ export function defineEntity(entity, opts = {}) {
     for (const index of opts.indexes ?? []) {
         defineIndex(entity, index);
     }
-    for (const [name, spec] of Object.entries(opts.filters ?? {})) {
-        if (spec)
-            defineFilter(entity, name, spec);
+    for (const [name, filter] of Object.entries(opts.filters ?? {})) {
+        if (filter)
+            defineFilter(entity, name, filter);
     }
     if (!hasKeys(meta.fields)) {
         throw TypeError(`'${entity.name}' must have fields`);
     }
-    meta.name = opts.name ?? entity.name;
-    meta.schema = opts.schema;
+    // A later call composes onto the entity, so saying nothing about the table retracts nothing - which
+    // is why `derivedName` is only ever *set*, never recomputed from what a previous call left.
+    // It records that the class name stood in, telling a naming strategy there is something to derive;
+    // comparing the two cannot, since an entity may name its table exactly what its class is called and
+    // a spec's minted class is named after its table.
+    if (opts.name !== undefined) {
+        meta.name = opts.name;
+        meta.derivedName = false;
+    }
+    else if (meta.name === undefined) {
+        meta.name = entity.name;
+        meta.derivedName = true;
+    }
+    meta.schema = opts.schema ?? meta.schema;
     let proto = Object.getPrototypeOf(entity.prototype);
     while (proto.constructor !== Object) {
         const parent = proto.constructor;
@@ -203,20 +230,38 @@ export function idOf(meta, row) {
     }
     return Object.fromEntries(ids.map((key) => [key, row[key]]));
 }
+/**
+ * Forgets an entity, and reports whether there was one - for a registry that grows at runtime, where a
+ * deleted content type would otherwise keep its metadata for the life of the process. Nothing rewrites
+ * what pointed at it, and a decorated class does not come back (its decorators drained at first
+ * registration). See the Runtime Schemas guide.
+ */
+export function removeEntity(entity) {
+    return metas.delete(entity);
+}
 export function getEntities() {
-    return [...metas.entries()].reduce((acc, [key, val]) => {
+    return metas.entries().reduce((acc, [key, val]) => {
         if (val.ids.length) {
             acc.push(key);
         }
         return acc;
     }, []);
 }
+/**
+ * The metadata of `entity`, marked as changed. Every `define*` goes through this, and nothing outside
+ * this file writes to a meta, so it is the one place a derived cache can be told it has gone stale.
+ */
+function ensureWritableMeta(entity) {
+    const meta = ensureMeta(entity);
+    meta.revision++;
+    return meta;
+}
 function ensureMeta(entity) {
     let meta = metas.get(entity);
     if (meta) {
         return meta;
     }
-    meta = { entity, ids: [], fields: {}, relations: {} };
+    meta = { entity, ids: [], fields: {}, relations: {}, revision: 0 };
     metas.set(entity, meta);
     return meta;
 }
@@ -225,10 +270,13 @@ export function getMeta(entity) {
     if (!meta) {
         throw TypeError(`'${entity.name}' is not an entity`);
     }
-    if (meta.processed) {
+    if (meta.processedAt === meta.revision) {
         return meta;
     }
-    meta.processed = true;
+    // Stamped before finalizing, not after: `fillInverseSide` reads the other side through `getMeta`,
+    // and with each side mapped by the other that recursion has to find this half-filled meta rather
+    // than run again. Finalizing twice is harmless anyway - every step of it skips what it settled.
+    meta.processedAt = meta.revision;
     return fillRelations(meta);
 }
 function fillRelations(meta) {
@@ -374,7 +422,7 @@ function fillForeignKeyRelations(meta) {
 }
 /** `<entityName><IdColumn>`, not the `<relationKey>Id` an owning to-one derives: a junction row has no relation key to borrow from. */
 function junctionColumn(meta, idKey) {
-    return lowerFirst(meta.name ?? '') + upperFirst(meta.fields[idKey]?.name ?? idKey);
+    return lowerFirst(entityName(meta)) + upperFirst(meta.fields[idKey]?.name ?? idKey);
 }
 /** A callback only reads one property off the key map, and that property is the key, so one serves every entity. */
 const RELATION_KEY_MAP = new Proxy({}, { get: (_, key) => key });

package/dist/http/handler.d.ts

@@ -51,6 +51,14 @@ export type ResponseHook<Ctx = unknown> = <E extends object>(ctx: HookContext<E,
 export type RequestHandlerOptions<Ctx = unknown> = {
     include?: Type<any>[];
     exclude?: Type<any>[];
+    /**
+     * The URL segment an entity is addressed by, defaulting to its kebab-cased class name.
+     *
+     * State it where the default cannot serve: a build that minifies class names renames every route,
+     * and two entities mapping one table in different schemas collide on one. The browser client takes
+     * the same option, so both ends can read one map.
+     */
+    entityPath?: (entity: Type<unknown>) => string;
     /**
      * Allow augment any kind of request before it runs. Hooks may be async
      * and abort the request by throwing (a numeric `status` on the error is honored).

package/dist/http/handler.js

@@ -9,6 +9,7 @@ function tableOf(entity) {
 }
 export function createRequestHandler(opts) {
     const { include, exclude, pre, preSave, preFilter, post, getContext, pool } = opts;
+    const pathOf = opts.entityPath ?? entityPath;
     let entities = include ?? getEntities();
     if (exclude) {
         entities = entities.filter((entity) => !exclude.includes(entity));
@@ -16,15 +17,14 @@ export function createRequestHandler(opts) {
     if (!entities.length) {
         throw new TypeError('no entities for the uql middleware');
     }
-    // The route is the class name, so two entities mapping one table in different schemas collide here
-    // even though nothing else about them does. All of them at once, so fixing the first collision
-    // does not just reveal the next.
-    const byPath = Map.groupBy(entities, entityPath);
+    // All of them at once, so fixing the first collision does not just reveal the next.
+    const byPath = Map.groupBy(entities, pathOf);
     const collisions = [...byPath].filter(([, clashing]) => clashing.length > 1);
     if (collisions.length) {
         const lines = collisions.map(([path, clashing]) => `  /${path} <- ${clashing.map(tableOf).join(', ')}`);
         throw new TypeError(`every entity below shares a route with another, so all but the first are unreachable:\n${lines.join('\n')}\n` +
-            "A route is the kebab-cased class name. Rename a class, or pass only one of them in 'include'.");
+            "A route is the kebab-cased class name unless 'entityPath' says otherwise. Name them apart, " +
+            "pass an 'entityPath', or pass only one of them in 'include'.");
     }
     // oxlint-disable-next-line typescript/no-explicit-any -- heterogeneous entity map
     const entityByPath = new Map([...byPath].map(([path, [entity]]) => [path, entity]));

package/dist/maria/mariaDialect.js

@@ -1,7 +1,7 @@
 import { jsonPath } from '../dialect/jsonSql.js';
 import { MysqlLikeSqlDialect } from '../dialect/mysqlLikeSqlDialect.js';
-import { isVectorFieldType } from '../dialect/vectorCast.js';
 import { getMeta } from '../entity/index.js';
+import { columnFamily } from '../util/field.util.js';
 import { MARIA_VECTOR_METRICS } from './mariaVectorMetrics.js';
 export class MariaDialect extends MysqlLikeSqlDialect {
     dialectName = 'mariadb';
@@ -76,6 +76,6 @@ export class MariaDialect extends MysqlLikeSqlDialect {
     }
     /** The reverse: selecting a `VECTOR` column raw yields that blob, so it is read back as text. */
     selectFieldExpr(escapedColumn, field) {
-        return isVectorFieldType(field.type) ? `VEC_ToText(${escapedColumn})` : escapedColumn;
+        return columnFamily(field.type) === 'vector' ? `VEC_ToText(${escapedColumn})` : escapedColumn;
     }
 }

package/dist/migrate/cli.d.ts

@@ -14,6 +14,11 @@ export declare function runStatus(migrator: Migrator): Promise<void>;
 export declare function runPending(migrator: Migrator): Promise<void>;
 export declare function runGenerate(migrator: Migrator, args: string[]): Promise<void>;
 export declare function runGenerateFromEntities(migrator: Migrator, args: string[]): Promise<void>;
+/**
+ * Writes a `.d.ts` for the registered entities. The point is a schema defined at runtime: the same
+ * registration that made the tables is what the compiler then checks queries against.
+ */
+export declare function runTypes(migrator: Migrator, args: string[]): void;
 export declare function runSync(migrator: Migrator, args: string[], config: Partial<Config>): Promise<void>;
 export declare function runGenerateFromDb(migrator: Migrator, args: string[], config: Partial<Config>): Promise<void>;
 export declare function runDriftCheck(migrator: Migrator, config: Partial<Config>): Promise<void>;

package/dist/migrate/cli.js

@@ -4,6 +4,7 @@ import * as path from 'node:path';
 import { assertCliConfig } from './assertCliConfig.js';
 import { loadConfig } from './cli-config.js';
 import { createEntityCodeGenerator } from './codegen/entityCodeGenerator.js';
+import { entityTypesSource } from './codegen/entityTypes.js';
 import { detectDrift } from './drift/driftDetector.js';
 import { Migrator } from './migrator.js';
 import { buildEntityAST, createSchemaGenerator } from './schemaGenerator.js';
@@ -74,6 +75,9 @@ export async function main(args = process.argv.slice(2)) {
             case 'sync':
                 await runSync(migrator, filteredArgs.slice(1), config);
                 break;
+            case 'types':
+                runTypes(migrator, filteredArgs.slice(1));
+                break;
             case 'pending':
                 await runPending(migrator);
                 break;
@@ -189,35 +193,45 @@ export async function runGenerateFromEntities(migrator, args) {
     const filePath = await migrator.generateFromEntities(name);
     console.log(`\nCreated migration from entities: ${filePath}`);
 }
+/**
+ * Writes a `.d.ts` for the registered entities. The point is a schema defined at runtime: the same
+ * registration that made the tables is what the compiler then checks queries against.
+ */
+export function runTypes(migrator, args) {
+    const output = readOutput(args) ?? './uql-entities.d.ts';
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    fs.writeFileSync(output, entityTypesSource(migrator.entities), 'utf-8');
+    console.log(`Wrote ${migrator.entities.length} entities to ${output}`);
+}
+/** `--output`/`-o`, wherever a command takes one. */
+function readOutput(args) {
+    const at = args.findIndex((arg) => arg === '--output' || arg === '-o');
+    return at === -1 ? undefined : args[at + 1];
+}
 export async function runSync(migrator, args, config) {
-    if (args.includes('--force')) {
-        console.log('\n⚠️  WARNING: This will drop and recreate all tables!');
-        console.log('   All data will be lost. This should only be used in development.\n');
-        await migrator.sync({ force: true });
-        console.log('\nSchema sync completed.');
-        return;
-    }
     // Pulling the database into entity files is what `generate:from-db` does; one implementation.
     if (args.includes('--pull')) {
         return runGenerateFromDb(migrator, args, config);
     }
+    const force = args.includes('--force');
     const safe = !args.includes('--unsafe');
+    const options = { force, safe, drop: !safe };
+    // Ahead of the warning as well as of the run: `--dry-run` means the same thing whatever else was
+    // asked for, and it used to be ignored beside `--force`.
     if (args.includes('--dry-run')) {
-        const statements = await migrator.planSync({ safe, drop: !safe });
+        const statements = await migrator.planSync(options);
         console.log(statements.length ? `\n${statements.join('\n')}` : '\nSchema is already in sync.');
         return;
     }
-    await migrator.autoSync({ safe, drop: !safe, logging: true });
+    if (force) {
+        console.log('\n⚠️  WARNING: This will drop and recreate all tables!');
+        console.log('   All data will be lost. This should only be used in development.\n');
+    }
+    await migrator.sync({ ...options, logging: true });
     console.log('\nSchema sync completed.');
 }
 export async function runGenerateFromDb(migrator, args, config) {
-    // Parse output directory
-    let outputDir = './src/entities';
-    for (let i = 0; i < args.length; i++) {
-        if ((args[i] === '--output' || args[i] === '-o') && args[i + 1]) {
-            outputDir = args[++i];
-        }
-    }
+    const outputDir = readOutput(args) ?? './src/entities';
     if (!migrator.schemaIntrospector) {
         console.error('No introspector available. Check your pool configuration.');
         process.exit(1);
@@ -342,6 +356,9 @@ Commands:
     --pull              Go the other way: generate entities from the database
     --force             Drop and recreate all tables (dangerous!)
 
+  types                 Write a .d.ts for the registered entities
+    --output, -o <file> Output path (default: ./uql-entities.d.ts)
+
   drift:check           Check for schema drift between entities and database
 
 Configuration:

package/dist/migrate/codegen/entityTypes.d.ts

@@ -0,0 +1,7 @@
+import type { Type } from '../../type/index.js';
+/**
+ * A `.d.ts` for the entities as registered, so a shape that only exists at runtime reaches the
+ * compiler too. Interfaces, not the entity classes `generate:from-db` writes: those are the source of
+ * a schema, these describe one already defined elsewhere.
+ */
+export declare function entityTypesSource(entities: readonly Type<unknown>[]): string;

package/dist/migrate/codegen/entityTypes.js

@@ -0,0 +1,69 @@
+import { getMeta } from '../../entity/index.js';
+import { canonicalToTypeScript } from '../../schema/canonicalType.js';
+import { resolveColumnCanonicalType } from '../../schema/schemaASTBuilder.js';
+import { isToManyRelation, upperFirst } from '../../util/index.js';
+/**
+ * A `.d.ts` for the entities as registered, so a shape that only exists at runtime reaches the
+ * compiler too. Interfaces, not the entity classes `generate:from-db` writes: those are the source of
+ * a schema, these describe one already defined elsewhere.
+ */
+export function entityTypesSource(entities) {
+    const metas = [...entities]
+        .map((entity) => getMeta(entity))
+        .sort((a, b) => a.entity.name.localeCompare(b.entity.name));
+    const names = interfaceNames(metas);
+    const interfaces = metas.map((meta) => {
+        const members = [
+            ...Object.entries(meta.fields).map(([key, field]) => member(key, fieldType(field))),
+            ...Object.entries(meta.relations).map(([key, rel]) => member(key, relationType(rel, names))),
+        ];
+        return `export interface ${names.get(meta.entity)} {\n${members.join('\n')}\n}`;
+    });
+    return ['// Generated by `uql-migrate types`. Do not edit.', '', ...interfaces, ''].join('\n');
+}
+/**
+ * One interface name per entity, settled before anything is written so a relation and its target
+ * agree. A class minted at runtime is named after the content type it came from, which nothing stops
+ * from carrying a dash or colliding with another once the dashes are gone - and either would emit a
+ * file that does not compile.
+ */
+function interfaceNames(metas) {
+    const taken = new Set();
+    return new Map(metas.map((meta) => {
+        const base = identifier(upperFirst(meta.entity.name));
+        let name = base;
+        for (let n = 2; taken.has(name); n++) {
+            name = `${base}${n}`;
+        }
+        taken.add(name);
+        return [meta.entity, name];
+    }));
+}
+/** `text` as an identifier: what cannot be in one is dropped, and what cannot start one is prefixed. */
+function identifier(text) {
+    const stripped = text.replace(/[^A-Za-z0-9_$]/g, '');
+    return /^[A-Za-z_$]/.test(stripped) ? stripped : `Entity${stripped}`;
+}
+/** A column name a property cannot hold - `hero-image` - is quoted rather than dropped. */
+function member(key, type) {
+    const name = key === identifier(key) ? key : JSON.stringify(key);
+    return `  ${name}?: ${type};`;
+}
+/**
+ * The property type a column reads back as, resolved the way the DDL resolves it - so a foreign key
+ * reports the type of the key it points at rather than the fallback its own options carry.
+ */
+function fieldType(field) {
+    return field ? canonicalToTypeScript(resolveColumnCanonicalType(field)) : 'unknown';
+}
+/**
+ * A relation is the related interface, a list where the cardinality says so - and `unknown` where the
+ * target is outside the set, since naming an interface the file does not declare would not compile.
+ */
+function relationType(relation, names) {
+    const target = relation && names.get(relation.entity());
+    if (!target) {
+        return 'unknown';
+    }
+    return isToManyRelation(relation) ? `${target}[]` : target;
+}

package/dist/migrate/codegen/index.d.ts

@@ -4,4 +4,5 @@
  * Generates TypeScript entity code from database schemas.
  */
 export { createEntityCodeGenerator, EntityCodeGenerator, type EntityCodeGeneratorOptions, type GeneratedEntity, } from './entityCodeGenerator.js';
+export { entityTypesSource } from './entityTypes.js';
 export { buildSqlQuerierMigrationModule, EMPTY_MANUAL_MIGRATION_DOWN_INNER, EMPTY_MANUAL_MIGRATION_UP_INNER, emitSqlRunCall, emitSqlRunCalls, type SqlMigrationModuleOptions, } from './migrationFile.js';

package/dist/migrate/codegen/index.js

@@ -5,4 +5,5 @@
  */
 // Entity code generator
 export { createEntityCodeGenerator, EntityCodeGenerator, } from './entityCodeGenerator.js';
+export { entityTypesSource } from './entityTypes.js';
 export { buildSqlQuerierMigrationModule, EMPTY_MANUAL_MIGRATION_DOWN_INNER, EMPTY_MANUAL_MIGRATION_UP_INNER, emitSqlRunCall, emitSqlRunCalls, } from './migrationFile.js';

package/dist/migrate/drift/driftDetector.js

@@ -4,7 +4,7 @@
  * Detects schema drift between expected schema (from entities) and
  * actual database schema.
  */
-import { canonicalToSql } from '../../schema/canonicalType.js';
+import { canonicalToSql, engineType } from '../../schema/canonicalType.js';
 import { diffSchemas } from '../../schema/schemaASTDiffer.js';
 function resolveOptions(options) {
     return {
@@ -24,11 +24,15 @@ function resolveOptions(options) {
  */
 export function detectDrift(expectedAST, actualAST, options = {}) {
     const opts = resolveOptions(options);
+    const { dialect } = opts;
     const diff = diffSchemas(expectedAST, actualAST, {
         compareIndexes: opts.checkIndexes,
         indexFacets: opts.indexFacets,
         compareRelationships: opts.checkForeignKeys,
         excludeTables: opts.excludeTables,
+        // Without a dialect there is no engine to compare through, and `formatType` below then reports no
+        // type drift at all.
+        ...(dialect && { normalizeType: engineType(dialect) }),
     });
     const drifts = [
         ...detectTableDrifts(diff),

package/dist/migrate/generator/mongoSchemaGenerator.d.ts

@@ -39,7 +39,7 @@ export declare class MongoSchemaGenerator extends AbstractDialect implements Sch
      */
     generateCreateIndex(tableName: string, index: IndexSchema): string;
     generateDropIndex(tableName: string, indexName: string): string;
-    getSqlType(fieldOptions: FieldOptions, fieldType?: unknown): string;
+    getSqlType(fieldOptions: FieldOptions): string;
     generateCreateTableFromNode(table: TableNode, _options?: {
         ifNotExists?: boolean;
     }): string[];

package/dist/migrate/generator/mongoSchemaGenerator.js

@@ -120,7 +120,7 @@ export class MongoSchemaGenerator extends AbstractDialect {
             name: indexName,
         });
     }
-    getSqlType(fieldOptions, fieldType) {
+    getSqlType(fieldOptions) {
         return '';
     }
     generateCreateTableFromNode(table, _options) {

package/dist/migrate/index.d.ts

@@ -1,4 +1,4 @@
-export type { ColumnSchema, DialectName, ForeignKeySchema, IndexSchema, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorOptions, MongoQuerier, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlDialectName, SqlQuerier, SqlQueryDialect, TableSchema, } from '../type/index.js';
+export type { ColumnSchema, DialectName, ForeignKeySchema, IndexSchema, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorOptions, MongoQuerier, SchemaDiff, SchemaGenerator, SchemaIntrospector, SqlDialectName, SqlQuerier, SqlQueryDialect, SyncOptions, TableSchema, } from '../type/index.js';
 export { type Config, isSqlQuerier } from '../type/index.js';
 export { acquireQuerierForMigrations } from './acquireQuerierForMigrations.js';
 export { assertCliConfig } from './assertCliConfig.js';