uql-orm 0.43.0 → 0.45.0

package/dist/migrate/builder/tableBuilder.d.ts

@@ -16,6 +16,7 @@ export declare class TableBuilder implements ITableBuilder {
     private _foreignKeyBuilders;
     private _comment?;
     constructor(name: string);
+    /** Big, matching an entity's `@Id`: a key is spelled from this type, so it has to state the real one. */
     id(name?: string, options?: BaseColumnOptions): IColumnBuilder;
     integer(name: string, options?: BaseColumnOptions): IColumnBuilder;
     smallint(name: string, options?: BaseColumnOptions): IColumnBuilder;

package/dist/migrate/builder/tableBuilder.js

@@ -12,8 +12,8 @@ import { expr } from './expressions.js';
  */
 class TableForeignKeyBuilder {
     _columns;
-    _referencesTable;
-    _referencesColumns = [];
+    _referencedTable;
+    _referencedColumns = [];
     _onDelete = 'NO ACTION';
     _onUpdate = 'NO ACTION';
     _name;
@@ -21,8 +21,8 @@ class TableForeignKeyBuilder {
         this._columns = columns;
     }
     references(table, columns) {
-        this._referencesTable = table;
-        this._referencesColumns = columns;
+        this._referencedTable = table;
+        this._referencedColumns = columns;
         return this;
     }
     onDelete(action) {
@@ -41,13 +41,12 @@ class TableForeignKeyBuilder {
      * Build the foreign key definition.
      */
     build() {
-        if (!this._referencesTable)
+        if (!this._referencedTable)
             return undefined;
         return {
             name: this._name,
             columns: this._columns,
-            referencesTable: this._referencesTable,
-            referencesColumns: this._referencesColumns,
+            references: { table: this._referencedTable, columns: this._referencedColumns },
             onDelete: this._onDelete,
             onUpdate: this._onUpdate,
         };
@@ -66,8 +65,9 @@ export class TableBuilder {
     constructor(name) {
         this._name = name;
     }
+    /** Big, matching an entity's `@Id`: a key is spelled from this type, so it has to state the real one. */
     id(name = 'id', options = {}) {
-        return this.add(name, { category: 'integer' }, { ...options, primaryKey: true, autoIncrement: true });
+        return this.add(name, { category: 'integer', size: 'big' }, { ...options, primaryKey: true, autoIncrement: true });
     }
     integer(name, options) {
         return this.add(name, { category: 'integer' }, options);
@@ -217,8 +217,7 @@ export class TableBuilder {
                 foreignKeys.push({
                     name: col.foreignKey.name,
                     columns: [col.name],
-                    referencesTable: col.foreignKey.table,
-                    referencesColumns: col.foreignKey.columns,
+                    references: { table: col.foreignKey.table, columns: col.foreignKey.columns },
                     onDelete: col.foreignKey.onDelete,
                     onUpdate: col.foreignKey.onUpdate,
                 });

package/dist/migrate/builder/types.d.ts

@@ -6,6 +6,7 @@
  */
 import type { CanonicalType, ForeignKeyAction } from '../../schema/types.js';
 import type { IndexColumnInput, IndexOptions, IndexSchema } from '../../type/index.js';
+import type { ForeignKeySchema } from '../../type/migration.js';
 /**
  * Foreign key reference options.
  */
@@ -124,27 +125,10 @@ export interface TableDefinition {
     /** Index definitions */
     indexes: IndexSchema[];
     /** Foreign key definitions at table level */
-    foreignKeys: TableForeignKeyDefinition[];
+    foreignKeys: ForeignKeySchema[];
     /** Table comment */
     comment?: string;
 }
-/**
- * Table-level foreign key (for composite FKs).
- */
-export interface TableForeignKeyDefinition {
-    /** Constraint name */
-    name?: string;
-    /** Local columns */
-    columns: string[];
-    /** Referenced table */
-    referencesTable: string;
-    /** Referenced columns */
-    referencesColumns: string[];
-    /** Action on delete */
-    onDelete: ForeignKeyAction;
-    /** Action on update */
-    onUpdate: ForeignKeyAction;
-}
 /**
  * Type of migration operation.
  */
@@ -238,7 +222,7 @@ export interface DropIndexOperation extends MigrationOperation {
 export interface AddForeignKeyOperation extends MigrationOperation {
     type: 'addForeignKey';
     tableName: string;
-    foreignKey: TableForeignKeyDefinition;
+    foreignKey: ForeignKeySchema;
 }
 /**
  * Drop foreign key operation.

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/generator/definitionToNode.js

@@ -40,8 +40,8 @@ export function tableDefinitionToNode(def) {
                 columns: fkDef.columns.map((name) => columns.get(name)).filter((c) => c !== undefined),
             },
             to: {
-                table: { name: fkDef.referencesTable },
-                columns: fkDef.referencesColumns.map((name) => ({ name })),
+                table: { name: fkDef.references.table },
+                columns: fkDef.references.columns.map((name) => ({ name })),
             },
             onDelete: fkDef.onDelete,
             onUpdate: fkDef.onUpdate,

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

package/dist/migrate/introspection/abstractSqlSchemaIntrospector.d.ts

@@ -1,9 +1,6 @@
+import type { ForeignKeyAction } from '../../schema/types.js';
 import type { ColumnSchema, ForeignKeySchema, IndexSchema, QuerierPool, RawRow, SchemaIntrospector, SqlQuerier, TableSchema } from '../../type/index.js';
 import { BaseSqlIntrospector } from './baseSqlIntrospector.js';
-/**
- * Referential action type for foreign key constraints.
- */
-export type ReferentialAction = 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
 /**
  * Reads the rows of one statement while introspecting a table.
  *
@@ -72,7 +69,7 @@ export declare abstract class AbstractSqlSchemaIntrospector extends BaseSqlIntro
     /**
      * Normalize referential action string to standard type.
      */
-    protected normalizeReferentialAction(action: string): ReferentialAction | undefined;
+    protected normalizeReferentialAction(action: string): ForeignKeyAction | undefined;
     /**
      * Convert bigint/null values to number safely.
      */

package/dist/migrate/introspection/abstractSqlSchemaIntrospector.js

@@ -131,6 +131,8 @@ export class AbstractSqlSchemaIntrospector extends BaseSqlIntrospector {
                 return 'RESTRICT';
             case 'NO ACTION':
                 return 'NO ACTION';
+            case 'SET DEFAULT':
+                return 'SET DEFAULT';
             default:
                 return undefined;
         }

package/dist/migrate/introspection/baseSqlIntrospector.js

@@ -1,6 +1,7 @@
 import { canonicalColumnType } from '../../schema/canonicalType.js';
 import { createTableNode, SchemaAST } from '../../schema/schemaAST.js';
 import { escapeSqlId } from '../../util/index.js';
+import { derivedForeignKeyName } from '../../util/sql.util.js';
 /**
  * Base class for SQL introspectors with shared AST building logic.
  */
@@ -83,14 +84,14 @@ export class BaseSqlIntrospector {
             if (!fromTable)
                 continue;
             for (const fk of schema.foreignKeys) {
-                const toTable = tableNodes.get(fk.referencedTable);
+                const toTable = tableNodes.get(fk.references.table);
                 if (!toTable)
                     continue;
                 const fromColumns = fk.columns.flatMap((name) => fromTable.columns.get(name) ?? []);
-                const toColumns = fk.referencedColumns.flatMap((name) => toTable.columns.get(name) ?? []);
+                const toColumns = fk.references.columns.flatMap((name) => toTable.columns.get(name) ?? []);
                 if (fromColumns.length > 0 && toColumns.length > 0) {
                     const rel = {
-                        name: fk.name,
+                        name: fk.name ?? derivedForeignKeyName(schema.name, fk.columns),
                         type: fromColumns[0].isUnique ? 'OneToOne' : 'ManyToOne',
                         from: { table: fromTable, columns: fromColumns },
                         to: { table: toTable, columns: toColumns },

package/dist/migrate/introspection/mysqlIntrospector.js

@@ -123,8 +123,7 @@ export class MysqlSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         return results.map((row) => ({
             name: row.constraint_name,
             columns: (row.columns || '').split(','),
-            referencedTable: row.referenced_table,
-            referencedColumns: (row.referenced_columns || '').split(','),
+            references: { table: row.referenced_table, columns: (row.referenced_columns || '').split(',') },
             onDelete: this.normalizeReferentialAction(row.delete_rule),
             onUpdate: this.normalizeReferentialAction(row.update_rule),
         }));

package/dist/migrate/introspection/postgresIntrospector.js

@@ -204,8 +204,7 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         return results.map((row) => ({
             name: row.constraint_name,
             columns: row.columns,
-            referencedTable: row.referenced_table,
-            referencedColumns: row.referenced_columns,
+            references: { table: row.referenced_table, columns: row.referenced_columns },
             onDelete: this.normalizeReferentialAction(row.delete_rule),
             onUpdate: this.normalizeReferentialAction(row.update_rule),
         }));

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -113,8 +113,7 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
                 // derives it. Seeded from the columns, not the PRAGMA's row id, which nothing else knows.
                 name: derivedForeignKeyName(tableName, columns),
                 columns,
-                referencedTable: first.table,
-                referencedColumns: rows.map((r) => r.to),
+                references: { table: first.table, columns: rows.map((r) => r.to) },
                 onDelete: this.normalizeReferentialAction(first.on_delete),
                 onUpdate: this.normalizeReferentialAction(first.on_update),
             };

package/dist/migrate/migrator.d.ts

@@ -1,4 +1,4 @@
-import type { DialectName, LoggingOptions, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorOptions, MongoQuerier, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, Type } from '../type/index.js';
+import type { DialectName, LoggingOptions, Migration, MigrationDefinition, MigrationResult, MigrationStorage, MigratorOptions, MongoQuerier, Querier, QuerierPool, SchemaDiff, SchemaGenerator, SchemaIntrospector, SyncOptions, Type } from '../type/index.js';
 import { LoggerWrapper } from '../util/index.js';
 import type { IMigrationBuilder } from './builder/types.js';
 /**
@@ -88,31 +88,45 @@ export declare class Migrator {
     private introspectClaimedSchemas;
     findEntityForTable(tableName: string): Promise<Type<unknown> | undefined>;
     /**
-     * Sync schema directly (for development only - not for production!)
-     */
-    sync(options?: {
-        force?: boolean;
-    }): Promise<void>;
-    /**
-     * Drops and recreates all tables (Development only!)
+     * Applies the entity schema to the database: every registered entity, or the one `entity` names.
+     *
+     * The whole surface is this and {@link planSync}, which answers the same question without running
+     * it - `force` and a single entity included, so `--dry-run` means the same thing whatever else was
+     * asked for.
      */
-    syncForce(): Promise<void>;
+    sync(options?: SyncOptions): Promise<void>;
     /**
-     * Safely synchronizes the schema by only adding missing tables and columns.
+     * Every table dropped and recreated.
+     *
+     * Both directions span the whole entity set rather than looping an entity at a time. A per-entity
+     * AST cannot resolve a cross-entity foreign key, so the old create loop silently produced a schema
+     * with no referential integrity; and the old drop loop went in reverse *declaration* order, which
+     * says nothing about the relation graph and is rejected as soon as the constraints are really there.
      */
-    autoSync(options?: {
-        safe?: boolean;
-        drop?: boolean;
-        logging?: boolean;
-    }): Promise<void>;
+    private forceStatements;
     /**
-     * The DDL {@link autoSync} would run, without running it. Separate so `--dry-run` shows the real
+     * Sync one entity, for a schema that grows while the process runs: a content type an admin just
+     * created is one table to add, where the whole set would read the catalogue to work that out.
+     *
+     * The new-table case costs one existence check and creates with `IF NOT EXISTS`, so instances racing
+     * the same admin save settle instead of colliding. An existing table still pays for introspection,
+     * since a column diff needs the columns.
+     */
+    /** The DDL for one entity: {@link planSync} narrowed to the table it names. */
+    private planEntity;
+    /** An alter diff as statements, narrowed to what the caller allows. */
+    private alterFromDiff;
+    /** The same for one entity against the table it already has, and nothing where the two agree. */
+    private alterFromEntity;
+    /** The configured entities, with `entity` among them however the migrator was built. */
+    private entitiesWith;
+    /** The introspector for a claimed schema, which is the connection's own where none is claimed. */
+    private introspectorFor;
+    /**
+     * The DDL {@link sync} would run, without running it. Separate so `--dry-run` shows the real
      * statements rather than a summary of a second, differently-computed diff.
      */
-    planSync(options?: {
-        safe?: boolean;
-        drop?: boolean;
-    }): Promise<string[]>;
+    planSync(options?: SyncOptions): Promise<string[]>;
     /**
      * New tables are emitted together, never one at a time: a single-entity AST has no other table for a
      * relation to resolve against, so every cross-entity foreign key was dropped and generated schemas