uql-orm 0.43.0 → 0.45.0

package/dist/schema/schemaASTDiffer.js

@@ -65,7 +65,9 @@ export function diffSchemas(source, target, options = {}) {
     const indexDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.indexDiffs ?? []);
     const primaryKeyDiffs = tablesToAlter.flatMap((tableDiff) => tableDiff.primaryKeyDiff ?? []);
     // Relationships span tables, so they are compared over the whole schema rather than per table.
-    const relationshipDiffs = opts.compareRelationships ? diffRelationships(source, target, opts) : [];
+    const relationshipDiffs = opts.compareRelationships
+        ? diffRelationshipNodes(source.relationships, target.relationships, opts)
+        : [];
     const hasDifferences = tablesToCreate.length > 0 ||
         tablesToDrop.length > 0 ||
         tablesToAlter.length > 0 ||
@@ -167,7 +169,7 @@ function diffColumn(tableName, source, target, opts) {
     const differences = [];
     // Two things a key column implies rather than states, and catalogues report inconsistently: its
     // type, which is the dialect's serial spelling rather than one the entity chose and does not round
-    // trip (`BIGINT UNSIGNED AUTO_INCREMENT` reads back as `BIGINT(20) UNSIGNED`), and its nullability,
+    // trip (`BIGINT AUTO_INCREMENT` reads back as `BIGINT(20)`), and its nullability,
     // which is NOT NULL in every engine whatever is reported - SQLite's `PRAGMA table_info` says
     // `notnull: 0` for the `INTEGER PRIMARY KEY` that is the table's own rowid. Comparing either asked
     // to rewrite the column on every sync, and on SQLite, which cannot alter one at all, failed
@@ -179,6 +181,14 @@ function diffColumn(tableName, source, target, opts) {
     if (typeChanged) {
         differences.push(`type: ${formatType(source.type)} → ${formatType(target.type)}`);
     }
+    // Signedness is the one thing compared on a generated key, because it is the one part of the serial
+    // spelling that does round trip - and a key left unsigned refuses every foreign key pointing at it,
+    // since the referencing column takes its type from the canonical one, which is signed. Without this
+    // a database created before the serial became signed could never gain a foreign key.
+    const signednessChanged = generatedType && !!source.type.unsigned !== !!target.type.unsigned;
+    if (signednessChanged) {
+        differences.push(`type: ${formatType(source.type)} → ${formatType(target.type)}`);
+    }
     if (!impliedNotNull && source.nullable !== target.nullable) {
         differences.push(`nullable: ${target.nullable} → ${source.nullable}`);
     }
@@ -206,7 +216,7 @@ function diffColumn(tableName, source, target, opts) {
         // Only the type this diff actually reports: a column altered for its default carries no data loss,
         // and a generated key's type - never compared above - reads as unsigned against an entity that
         // cannot say so.
-        isBreaking: typeChanged && isBreakingTypeChange(target.type, source.type),
+        isBreaking: (typeChanged || signednessChanged) && isBreakingTypeChange(target.type, source.type),
         description: differences.join(', '),
     };
 }
@@ -228,11 +238,17 @@ function diffIndex(tableName, source, target, facets) {
     };
 }
 /**
- * Compare relationships at the schema level.
+ * Compare two lists of relationships.
+ *
+ * Lists rather than whole schemas, because a migration diffs one table: its two sides are that
+ * table's `outgoingRelations`, where `diffSchemas` passes the schema's every relationship.
+ *
+ * Matched by columns, never by name - the engine named every constraint that already exists, so
+ * pairing on names would report every hand-named one as a drop and an add.
  */
-function diffRelationships(source, target, opts) {
-    const normalizeName = nameNormalizer(opts);
-    const { created, dropped, matched } = matchByKey(source.relationships, target.relationships, (relation) => getRelationshipKey(relation, normalizeName));
+export function diffRelationshipNodes(source, target, opts = {}) {
+    const normalizeName = nameNormalizer({ ...DEFAULT_OPTIONS, ...opts });
+    const { created, dropped, matched } = matchByKey(source, target, (relation) => getRelationshipKey(relation, normalizeName));
     return [
         ...created.map((relation) => ({
             ...relationEnds(relation),

package/dist/schema/types.d.ts

@@ -272,14 +272,29 @@ export interface IndexDiff {
 /**
  * Difference between two relationship definitions.
  */
-export interface RelationshipDiff {
+interface RelationshipDiffBase {
     readonly name: string;
     readonly fromTable: string;
     readonly toTable: string;
-    readonly type: 'create' | 'drop' | 'alter';
-    readonly expected?: RelationshipNode;
-    readonly actual?: RelationshipNode;
 }
+/**
+ * Difference between two relationships, shaped like {@link ColumnDiff} and for the same reason: which
+ * node is present follows from the kind of difference, so a reader never asserts its way past an
+ * `undefined` the kind had already ruled out.
+ */
+export type RelationshipDiff = RelationshipDiffBase & ({
+    readonly type: 'create';
+    readonly expected: RelationshipNode;
+    readonly actual?: undefined;
+} | {
+    readonly type: 'drop';
+    readonly expected?: undefined;
+    readonly actual: RelationshipNode;
+} | {
+    readonly type: 'alter';
+    readonly expected: RelationshipNode;
+    readonly actual: RelationshipNode;
+});
 /**
  * Complete diff between two schemas.
  */

package/dist/sqlite/sqliteDialect.d.ts

@@ -5,7 +5,7 @@ export declare class SqliteDialect extends AbstractSqlDialect {
     protected readonly featureDefaults: DialectFeatures;
     readonly dialectName = "sqlite";
     readonly escapeIdChar = "`";
-    readonly serialType = "INTEGER PRIMARY KEY AUTOINCREMENT";
+    readonly autoIncrementSuffix = "PRIMARY KEY AUTOINCREMENT";
     readonly serialDeclaresPrimaryKey = true;
     readonly tableOptions = "";
     readonly beginTransactionCommand = "BEGIN TRANSACTION";

package/dist/sqlite/sqliteDialect.js

@@ -22,7 +22,7 @@ export class SqliteDialect extends AbstractSqlDialect {
     };
     dialectName = 'sqlite';
     escapeIdChar = '`';
-    serialType = 'INTEGER PRIMARY KEY AUTOINCREMENT';
+    autoIncrementSuffix = 'PRIMARY KEY AUTOINCREMENT';
     // `AUTOINCREMENT` is only legal in that exact phrase, so the key cannot be lifted to table level.
     serialDeclaresPrimaryKey = true;
     tableOptions = '';

package/dist/type/entity.d.ts

@@ -232,7 +232,7 @@ export type RelationValue<E> = E[RelationKey<E>];
 /**
  * SQL numeric column types
  */
-export type NumericColumnType = 'int' | 'integer' | 'tinyint' | 'smallint' | 'bigint' | 'float' | 'float4' | 'float8' | 'double' | 'double precision' | 'decimal' | 'numeric' | 'real' | 'serial' | 'smallserial' | 'bigserial';
+export type NumericColumnType = 'int' | 'integer' | 'tinyint' | 'smallint' | 'bigint' | 'float' | 'float4' | 'float8' | 'double' | 'double precision' | 'decimal' | 'numeric' | 'real';
 /**
  * SQL string column types
  */
@@ -741,7 +741,10 @@ export type EntityIndexMeta = {
 } & VectorIndexOptions & IndexTypeOptions;
 export type EntityMeta<E> = {
     readonly entity: Type<E>;
+    /** The table, which is the class's own name where the entity named none - see {@link derivedName}. */
     name?: string;
+    /** Whether {@link name} came from the class rather than from the author, so a naming strategy applies. */
+    derivedName?: boolean;
     /** Set only when the entity named one; unset defers to the pool where it is used. See `AbstractDialect.resolveSchema`. */
     schema?: string;
     /**
@@ -794,6 +797,16 @@ export type CheckOptions = {
     readonly name?: string;
     readonly expression: QueryRaw;
 };
+/**
+ * An entity's members as the registry takes them, keyed by plain strings - what a decorator bag, an
+ * {@link EntityOptions} and a decorator bag both reduce to before anything is registered: a member
+ * decorator has no class to key against, so by then the keys are plain strings either way.
+ */
+export type EntityMembers = {
+    readonly fields?: Readonly<Record<string, FieldOptions | undefined>>;
+    readonly relations?: Readonly<Record<string, RelationOptions | undefined>>;
+    readonly hooks?: Readonly<Partial<Record<HookEvent, readonly string[]>>>;
+};
 export type EntityOptions<E = unknown> = {
     readonly name?: string;
     /**

package/dist/type/migration.d.ts

@@ -1,5 +1,5 @@
 import type { VectorCast } from '../dialect/vectorCast.js';
-import type { FullColumnDefinition, TableDefinition, TableForeignKeyDefinition } from '../migrate/builder/types.js';
+import type { FullColumnDefinition, TableDefinition } from '../migrate/builder/types.js';
 import type { IndexFacet } from '../schema/indexDifferences.js';
 import type { SchemaAST } from '../schema/schemaAST.js';
 import type { ForeignKeyAction, IndexNode, IndexType, TableNode } from '../schema/types.js';
@@ -161,15 +161,25 @@ export interface IndexSchema extends VectorIndexOptions {
     readonly vectorType?: VectorCast;
 }
 /**
- * Represents a foreign key constraint
+ * A foreign key constraint, wherever one is described: read back by introspection, planned into a
+ * {@link SchemaDiff}, or declared through the migration builder. One shape for all three - they
+ * differed only in spelling, and the translation between them was pure overhead.
  */
 export interface ForeignKeySchema {
-    readonly name: string;
+    /** Absent when nothing named it, which the generator fills in with `derivedForeignKeyName`. */
+    readonly name?: string;
     readonly columns: string[];
-    readonly referencedTable: string;
-    readonly referencedColumns: string[];
-    readonly onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
-    readonly onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    /**
+     * The far end, as one thing. Same shape and same name as everywhere else a relationship's target is
+     * described - `@Field({ references })`, `addForeignKey`'s `target`, a `RelationshipNode`'s `to` -
+     * so nothing has to be destructured on the way between them.
+     */
+    readonly references: {
+        readonly table: string;
+        readonly columns: string[];
+    };
+    readonly onDelete?: ForeignKeyAction;
+    readonly onUpdate?: ForeignKeyAction;
 }
 /**
  * Represents a difference between current and desired schema
@@ -204,7 +214,30 @@ export interface SchemaDiff {
     readonly indexesToAdd?: IndexSchema[];
     readonly indexesToDrop?: string[];
     readonly foreignKeysToAdd?: ForeignKeySchema[];
+    /** Dropped under the name the *database* reported, which is the only name a `DROP` can use. */
     readonly foreignKeysToDrop?: string[];
+    /**
+     * A constraint whose referential actions changed. Its own field rather than a pair of entries in
+     * the two above, because no engine alters an action in place: it is a drop and an add that have to
+     * travel together, and safe mode has to hold back both or neither.
+     */
+    readonly foreignKeysToAlter?: {
+        readonly from: ForeignKeySchema;
+        readonly to: ForeignKeySchema;
+    }[];
+}
+/**
+ * What every sync entry point takes: `safe` keeps it additive, `drop` lets it remove a column, and
+ * `logging` reports each statement. A plan ignores `logging`, having nothing to run.
+ */
+export interface SyncOptions {
+    readonly safe?: boolean;
+    readonly drop?: boolean;
+    readonly logging?: boolean;
+    /** One entity instead of every registered one, for a schema that grows while the process runs. */
+    readonly entity?: Type<unknown>;
+    /** Drop every table and recreate it. Development only: it is the one option that loses data. */
+    readonly force?: boolean;
 }
 export interface CreateSchemaOptions {
     readonly ifNotExists?: boolean;
@@ -265,8 +298,21 @@ export interface SchemaGenerator {
     getSqlType(fieldOptions: FieldOptions): string;
     /**
      * Compare an entity with a database table node and return the differences.
+     *
+     * `desiredAst` is the entity side, from {@link buildAST}, and must span every entity a foreign key
+     * on this table points at: a relation whose target is absent resolves to nothing, so the constraint
+     * reads as missing from both sides, which is a match and no statement. Defaults to this entity
+     * alone, which is right only where it has no relations.
+     */
+    diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined, desiredAst?: SchemaAST): SchemaDiff | undefined;
+    /**
+     * The entity side as an AST, to hand to every {@link diffSchema} of one run - building it per
+     * entity instead is quadratic in the number of entities.
+     *
+     * Optional because not every generator compares one: MongoDB has no foreign keys and diffs only
+     * indexes, so it neither implements this nor reads the argument.
      */
-    diffSchema<E>(entity: Type<E>, currentTable: TableNode | undefined): SchemaDiff | undefined;
+    buildAST?(entities: readonly Type<unknown>[]): SchemaAST;
     /**
      * The table's key: {@link resolveTableAlias} behind {@link resolveSchema}, which is how a
      * `SchemaAST` stores it and how a diff finds it again.
@@ -313,7 +359,7 @@ export interface SqlDdlGenerator extends SchemaGenerator {
     /** Generate RENAME COLUMN statement */
     generateRenameColumnSql(tableName: string, oldName: string, newName: string): string;
     /** Generate ADD FOREIGN KEY statement */
-    generateAddForeignKeySql(tableName: string, foreignKey: TableForeignKeyDefinition): string;
+    generateAddForeignKeySql(tableName: string, foreignKey: ForeignKeySchema): string;
     /** Generate DROP FOREIGN KEY statement */
     generateDropForeignKeySql(tableName: string, constraintName: string): string;
 }

package/dist/type/queryWhere.d.ts

@@ -296,10 +296,20 @@ type QueryCommonOp = Exclude<keyof QueryWhereFieldOperatorMap<unknown>, QueryStr
 type QueryAllowedOp<T> = QueryCommonOp | ([NonNullable<T>] extends [QueryComparableScalar] ? QueryOrderedOp : never) | ([NonNullable<T>] extends [string] ? QueryStringOp : never) | ([NonNullable<T>] extends [readonly number[] | Uint8Array] ? QueryVectorOp : never) | (IsMany<T> extends true ? QueryArrayOp : never);
 /**
  * Operators applicable to a field of type `T`: string operators require string fields, ordering
- * operators comparable fields, array operators array fields. `unknown` stays fully permissive
- * (untyped JSON dot-paths, erased dialect shapes).
+ * operators comparable fields, array operators array fields.
+ *
+ * Two shapes stay fully permissive, because neither says anything to check against: `unknown`
+ * (untyped JSON dot-paths, erased dialect shapes), and a field typed as every scalar at once - the
+ * column of a content type defined at runtime. Narrowing to what they share would leave a dynamic
+ * row with equality alone, since no operator applies to a boolean and a blob both.
+ */
+export type QueryWhereFieldOperators<T> = unknown extends T ? QueryWhereFieldOperatorMap<T> : IsUntypedColumn<T> extends true ? QueryWhereFieldOperatorMap<T> : Pick<QueryWhereFieldOperatorMap<T>, QueryAllowedOp<T>>;
+/**
+ * Whether a column admits every scalar at once, which is what an entity keyed by an index signature
+ * says about all of its columns. `Scalar` is the yardstick rather than a parameter: the question is
+ * whether `T` is at least that wide, and nothing narrower than the whole union answers it.
  */
-export type QueryWhereFieldOperators<T> = unknown extends T ? QueryWhereFieldOperatorMap<T> : Pick<QueryWhereFieldOperatorMap<T>, QueryAllowedOp<T>>;
+type IsUntypedColumn<T> = [Scalar] extends [NonNullable<T>] ? true : false;
 /**
  * Value for a field comparison. A bare array is an implicit `$in` for scalar fields only:
  * on array-typed fields (e.g. a vector `number[]`) an array of arrays is ambiguous, so

package/dist/util/field.util.d.ts

@@ -12,7 +12,7 @@ export type ColumnFamily = 'string' | 'numeric' | 'boolean' | 'date' | 'json' |
  * restates the unions: the compile-time side of the same question reads them directly.
  */
 export declare const COLUMN_TYPES_BY_FAMILY: {
-    readonly numeric: readonly ["int", "integer", "tinyint", "smallint", "bigint", "float", "float4", "float8", "double", "double precision", "decimal", "numeric", "real", "serial", "smallserial", "bigserial"];
+    readonly numeric: readonly ["int", "integer", "tinyint", "smallint", "bigint", "float", "float4", "float8", "double", "double precision", "decimal", "numeric", "real"];
     readonly string: readonly ["char", "varchar", "text", "uuid"];
     readonly date: readonly ["date", "time", "datetime", "timestamp", "timestamptz"];
     readonly json: readonly ["json", "jsonb"];
@@ -33,6 +33,11 @@ export declare function columnFamily(type: unknown): ColumnFamily | undefined;
  */
 export declare function isSoleIdField<E>(meta: EntityMeta<E>, field: FieldOptions): boolean;
 /**
- * Checks if a field should be treated as auto-incrementing.
+ * Whether the database generates this column's value.
+ *
+ * The only answer: the schema AST asked it separately and disagreed on three counts - it ignored
+ * `onInsert`, so a key the application generates was still emitted `AUTO_INCREMENT`, and it ignored
+ * `columnType`, where this one used to let *any* declared width suppress the whole inference. A key
+ * that states its width is still a generated key; one that states how it is filled is not.
  */
 export declare function isAutoIncrement(field: FieldOptions, isPrimaryKey: boolean): boolean;

package/dist/util/field.util.js

@@ -20,9 +20,6 @@ export const COLUMN_TYPES_BY_FAMILY = {
         'decimal',
         'numeric',
         'real',
-        'serial',
-        'smallserial',
-        'bigserial',
     ],
     string: ['char', 'varchar', 'text', 'uuid'],
     date: ['date', 'time', 'datetime', 'timestamp', 'timestamptz'],
@@ -62,15 +59,15 @@ export function isSoleIdField(meta, field) {
     return field.isId === true && meta.ids.length === 1;
 }
 /**
- * Checks if a field should be treated as auto-incrementing.
+ * Whether the database generates this column's value.
+ *
+ * The only answer: the schema AST asked it separately and disagreed on three counts - it ignored
+ * `onInsert`, so a key the application generates was still emitted `AUTO_INCREMENT`, and it ignored
+ * `columnType`, where this one used to let *any* declared width suppress the whole inference. A key
+ * that states its width is still a generated key; one that states how it is filled is not.
  */
 export function isAutoIncrement(field, isPrimaryKey) {
-    if (field.autoIncrement === false)
-        return false;
-    if (field.autoIncrement)
-        return true;
-    const colType = field.columnType?.toLowerCase();
-    if (colType === 'serial' || colType === 'smallserial' || colType === 'bigserial')
-        return true;
-    return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert && !field.columnType;
+    if (field.autoIncrement !== undefined)
+        return field.autoIncrement;
+    return isPrimaryKey && columnFamily(field.type) === 'numeric' && !field.onInsert;
 }

package/dist/util/object.util.d.ts

@@ -21,9 +21,9 @@ export declare function isOperatorObject(value: unknown): value is Record<string
 export declare function isOperatorOnlyObject(value: unknown): value is Record<string, unknown>;
 export declare function getKeys<T extends object>(obj: T): (keyof T & string)[];
 /**
- * The entity's own name for a message to carry, declared or its class's. `defineEntity` always sets
- * one, so the fallback is for a meta a decorator is still building - which is why the sites spelling
- * this out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
+ * The entity's own name, declared or its class's. `meta.name` holds only what the author wrote, so
+ * the fallback is what an entity that named no table is called - which is why the sites spelling this
+ * out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
  */
 export declare function entityName<E>(meta: EntityMeta<E>): string;
 export declare function getFieldKeys<E>(fields: {

package/dist/util/object.util.js

@@ -53,9 +53,9 @@ export function getKeys(obj) {
     return obj ? Object.keys(obj) : [];
 }
 /**
- * The entity's own name for a message to carry, declared or its class's. `defineEntity` always sets
- * one, so the fallback is for a meta a decorator is still building - which is why the sites spelling
- * this out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
+ * The entity's own name, declared or its class's. `meta.name` holds only what the author wrote, so
+ * the fallback is what an entity that named no table is called - which is why the sites spelling this
+ * out reached for three different fallbacks, `?? ''` among them, and named nothing at all.
  */
 export function entityName(meta) {
     return meta.name ?? meta.entity.name;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "uql-orm",
   "homepage": "https://uql-orm.dev",
-  "description": "JSON-native TypeScript ORM for Node.js, Bun and Deno. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
+  "description": "The JSON-native TypeScript ORM for Bun, Browsers, Edge, Deno, Node, Workers. Supports PostgreSQL, PGlite, MySQL, MariaDB, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.",
   "license": "MIT",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -145,7 +145,7 @@
     "express": "^5.2.1",
     "mariadb": "^3.5.4",
     "mongodb": "^7.6.0",
-    "mysql2": "^3.24.3",
+    "mysql2": "^3.24.4",
     "pg": "^8.23.0",
     "pg-query-stream": "^4.17.0",
     "rxjs": "^7.8.2",