uql-orm 0.24.6 → 0.25.0

package/dist/querier/abstractSqlQuerier.js

@@ -1,3 +1,4 @@
+import { decodeColumn } from '../dialect/hydrateColumn.js';
 import { getMeta } from '../entity/index.js';
 import { buildUpdateResult, clone, getInsertFieldKeys, getRelationRequestSummary, isAutoIncrement, obtainAttrsPaths, throwNoPendingTransaction, throwPendingTransaction, unflatObject, unflatObjects, withoutSoftDeleteFilter, } from '../util/index.js';
 import { AbstractQuerier } from './abstractQuerier.js';
@@ -54,7 +55,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         const ctx = this.dialect.createContext();
         this.dialect.find(ctx, entity, q, opts);
         const res = await this.all(ctx.sql, ctx.values);
-        const founds = unflatObjects(res).map((row) => this.hydrateJsonFields(entity, row));
+        const founds = unflatObjects(res).map((row) => this.hydrateFields(entity, row));
         await this.fillToManyRelations(entity, founds, q.$populate);
         return founds;
     }
@@ -74,7 +75,7 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         try {
             for await (const row of this.internalStream(ctx.sql, normalizedParams)) {
                 attrsPaths ??= obtainAttrsPaths(row);
-                yield this.hydrateJsonFields(entity, unflatObject(row, attrsPaths));
+                yield this.hydrateFields(entity, unflatObject(row, attrsPaths));
             }
         }
         catch (err) {
@@ -90,31 +91,25 @@ export class AbstractSqlQuerier extends AbstractQuerier {
         const rows = await this.internalAll(query, this.dialect.normalizeValues(values));
         yield* rows;
     }
-    hydrateJsonFields(entity, dto) {
-        this.hydrateJsonFieldsRecursive(entity, dto, new WeakSet());
-        return dto;
-    }
-    hydrateJsonFieldsRecursive(entity, dto, visited) {
+    /**
+     * Turn what a driver returned back into the types the entity declares, for the row and everything
+     * populated under it. Which columns, and as what, is `hydratableFields`; the per-cell decode is
+     * `decodeColumn`. Both live with the dialect, because a `sparsevec` is only sparse on Postgres.
+     *
+     * `visited` guards a populated graph that points back at itself; it defaults rather than living in
+     * a separate entry-point wrapper, because the wrapper's whole body was seeding it.
+     */
+    hydrateFields(entity, dto, visited = new WeakSet()) {
         if (!dto || typeof dto !== 'object' || visited.has(dto)) {
-            return;
+            return dto;
         }
         visited.add(dto);
         const meta = getMeta(entity);
         const row = dto;
-        for (const key in meta.fields) {
-            const field = meta.fields[key];
-            if (!field || (field.type !== 'json' && field.type !== 'jsonb')) {
-                continue;
-            }
+        for (const [key, kind] of this.dialect.hydratableFields(entity)) {
             const value = row[key];
-            if (typeof value !== 'string') {
-                continue;
-            }
-            try {
-                row[key] = JSON.parse(value);
-            }
-            catch {
-                // Keep the original value when the driver returns non-JSON text.
+            if (value != null) {
+                row[key] = decodeColumn(value, kind);
             }
         }
         for (const key in meta.relations) {
@@ -125,26 +120,38 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             const value = row[key];
             if (Array.isArray(value)) {
                 for (const it of value) {
-                    this.hydrateJsonFieldsRecursive(relEntity, it, visited);
+                    this.hydrateFields(relEntity, it, visited);
                 }
                 continue;
             }
             if (value && typeof value === 'object') {
-                this.hydrateJsonFieldsRecursive(relEntity, value, visited);
+                this.hydrateFields(relEntity, value, visited);
             }
         }
+        return dto;
     }
     async internalCount(entity, q = {}, opts) {
         const ctx = this.dialect.createContext();
         this.dialect.count(ctx, entity, q, opts);
         const res = await this.all(ctx.sql, ctx.values);
+        // `COUNT(*)` is BIGINT, which the pools decode at the wire - but a caller who supplies their own
+        // `types` replaces that, and the signature promises a number here regardless.
         return Number(res[0].count);
     }
     async internalAggregate(entity, q, opts) {
         const ctx = this.dialect.createContext();
         this.dialect.aggregate(ctx, entity, q, opts);
         // biome-ignore lint/suspicious/noExplicitAny: raw DB rows satisfy QueryAggregateResult at runtime but TS can't verify
-        return this.all(ctx.sql, ctx.values);
+        const res = await this.all(ctx.sql, ctx.values);
+        const hydratable = this.dialect.hydratableAggregates(entity, q);
+        for (const row of res) {
+            for (const [alias, kind] of hydratable) {
+                if (row[alias] != null) {
+                    row[alias] = decodeColumn(row[alias], kind);
+                }
+            }
+        }
+        return res;
     }
     async internalInsertMany(entity, payload) {
         if (!payload?.length) {
@@ -224,10 +231,12 @@ export class AbstractSqlQuerier extends AbstractQuerier {
             return 0;
         }
         const ids = founds.map((it) => it[meta.id]);
+        // Children first: they hold the foreign key, so deleting the parent ahead of them is rejected
+        // outright by any schema that declares the constraint without `ON DELETE CASCADE`.
+        await this.deleteRelations(entity, ids, opts);
         const deleteCtx = this.dialect.createContext();
         this.dialect.delete(deleteCtx, entity, { $where: ids }, opts);
         const { changes = 0 } = await this.run(deleteCtx.sql, deleteCtx.values);
-        await this.deleteRelations(entity, ids, opts);
         return changes;
     }
     get hasOpenTransaction() {

package/dist/schema/canonicalType.js

@@ -6,15 +6,10 @@
  * - Canonical types (dialect-agnostic)
  * - TypeScript types (for entity generation)
  */
-// ============================================================================
-// Vector Category Helpers
-// ============================================================================
 /** Whether a category is one of the vector types, narrowing it to the cast pgvector names use. */
 export function isVectorCategory(category) {
     return category === 'vector' || category === 'halfvec' || category === 'sparsevec';
 }
-// Type Mapping Tables
-// ============================================================================
 /**
  * Maps SQL type strings to canonical type categories.
  * Handles variations across dialects (PostgreSQL, MySQL, SQLite).
@@ -250,9 +245,6 @@ const CANONICAL_TO_TS = {
     halfvec: 'number[]',
     sparsevec: 'number[]',
 };
-// ============================================================================
-// Type Conversion Functions
-// ============================================================================
 /**
  * Parse a SQL type string into a canonical type.
  * Handles complex types like VARCHAR(255), DECIMAL(10,2), etc.
@@ -426,10 +418,8 @@ export function fieldOptionsToCanonical(options, tsType) {
                 scale: options.scale,
             };
         }
-        // Infer bigint for Number if autoIncrement is true or if it's a primary key
-        if (options.autoIncrement || options.isId) {
-            return { category: 'integer', size: 'big' };
-        }
+        // BIGINT for every `Number`, key or not: a 32-bit column is a migration waiting to happen, and
+        // the pools decode it back to a JS number at the wire (see `pgNumericTypes`).
         return { category: 'integer', size: 'big' };
     }
     if (type === Boolean) {

package/dist/schema/schemaAST.js

@@ -18,9 +18,6 @@ export class SchemaAST {
     tables = new Map();
     relationships = [];
     indexes = [];
-    // ============================================================================
-    // Table Operations
-    // ============================================================================
     /**
      * Get a table by name.
      */
@@ -68,9 +65,6 @@ export class SchemaAST {
     getTableNames() {
         return Array.from(this.tables.keys());
     }
-    // ============================================================================
-    // Graph Navigation
-    // ============================================================================
     /**
      * Get all tables that depend on this table (have FKs pointing to it).
      * These are tables that reference this table's primary key.
@@ -103,9 +97,6 @@ export class SchemaAST {
     getReferencedColumn(fkColumn) {
         return fkColumn.references?.to.columns[0];
     }
-    // ============================================================================
-    // Graph Analysis
-    // ============================================================================
     /**
      * Detect circular foreign key dependencies.
      * Returns arrays of tables that form cycles.
@@ -179,9 +170,6 @@ export class SchemaAST {
         }
         return result;
     }
-    // ============================================================================
-    // Validation
-    // ============================================================================
     /**
      * Validate schema integrity.
      * Checks for:
@@ -233,9 +221,6 @@ export class SchemaAST {
     isValid() {
         return this.validate().length === 0;
     }
-    // ============================================================================
-    // Smart Relation Detection
-    // ============================================================================
     /**
      * Check if a table looks like a junction table (ManyToMany through).
      * Junction tables typically have:
@@ -292,9 +277,6 @@ export class SchemaAST {
                 return 'ManyToMany';
         }
     }
-    // ============================================================================
-    // Index Operations
-    // ============================================================================
     /**
      * Add an index to the schema.
      */
@@ -317,9 +299,6 @@ export class SchemaAST {
     getIndex(name) {
         return this.indexes.find((i) => i.name === name);
     }
-    // ============================================================================
-    // Relationship Operations
-    // ============================================================================
     /**
      * Add a relationship to the schema.
      */
@@ -365,9 +344,6 @@ export class SchemaAST {
         this.relationships.splice(index, 1);
         return true;
     }
-    // ============================================================================
-    // Utility Methods
-    // ============================================================================
     /**
      * Create a deep clone of this schema.
      */

package/dist/schema/schemaASTBuilder.d.ts

@@ -41,7 +41,7 @@ export declare class SchemaASTBuilder {
     /**
      * Build AST from entity classes (decorated with @Entity, @Field, etc.)
      */
-    fromEntities(entities: Type<unknown>[], options?: BuildFromEntitiesOptions): SchemaAST;
+    fromEntities(entities: readonly Type<unknown>[], options?: BuildFromEntitiesOptions): SchemaAST;
     /**
      * Resolve the canonical type for a field, inheriting from the referenced
      * entity's primary key when the field is a foreign-key reference

package/dist/schema/schemaASTBuilder.js

@@ -34,9 +34,6 @@ export class SchemaASTBuilder {
     getAST() {
         return this.ast;
     }
-    // ============================================================================
-    // Build from Entities
-    // ============================================================================
     /**
      * Build AST from entity classes (decorated with @Entity, @Field, etc.)
      */
@@ -184,8 +181,10 @@ export class SchemaASTBuilder {
                         type: relation.cardinality === 'm1' ? 'ManyToOne' : 'OneToOne',
                         from: { table, columns: [localColumn] },
                         to: { table: relatedTable, columns: [foreignColumn] },
-                        onDelete: options.defaultForeignKeyAction ?? this.defaultForeignKeyAction,
-                        onUpdate: options.defaultForeignKeyAction ?? this.defaultForeignKeyAction,
+                        // The relation's own action wins over the global default, so one relation can cascade in the
+                        // database while the rest stay on `NO ACTION`.
+                        onDelete: relation.onDelete ?? options.defaultForeignKeyAction ?? this.defaultForeignKeyAction,
+                        onUpdate: relation.onUpdate ?? options.defaultForeignKeyAction ?? this.defaultForeignKeyAction,
                         confidence: 1.0,
                         inferredFrom: 'entity_decorator',
                     };

package/dist/sqlite/nodeSqliteQuerierPool.js

@@ -24,6 +24,7 @@ export class NodeSqliteQuerierPool extends AbstractLocalSqliteQuerierPool {
             ...(extensions?.length ? { allowExtension: true } : undefined),
         });
         nodeDb.exec('PRAGMA journal_mode = WAL');
+        nodeDb.exec('PRAGMA foreign_keys = ON');
         return adaptNodeSqlite(nodeDb);
     }
 }

package/dist/sqlite/sqliteQuerierPool.d.ts

@@ -11,5 +11,10 @@ export type Sqlite3PoolOptions = Options & LocalSqlitePoolOptions;
 export declare class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool<Sqlite3PoolOptions> {
     readonly filename: string | Buffer;
     constructor(filename?: string | Buffer, opts?: Sqlite3PoolOptions, extra?: ExtraOptions);
+    /**
+     * SQLite ships with foreign keys unenforced, per connection, for backward compatibility. UQL emits the
+     * constraints in its DDL, so leaving them off means a declared `onDelete: 'CASCADE'` silently does
+     * nothing and a dangling reference is accepted. Enabled here on every driver, as TypeORM also does.
+     */
     protected createDb(): Promise<SqliteDatabase>;
 }

package/dist/sqlite/sqliteQuerierPool.js

@@ -9,6 +9,11 @@ export class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool {
         super(opts, extra);
         this.filename = filename;
     }
+    /**
+     * SQLite ships with foreign keys unenforced, per connection, for backward compatibility. UQL emits the
+     * constraints in its DDL, so leaving them off means a declared `onDelete: 'CASCADE'` silently does
+     * nothing and a dangling reference is accepted. Enabled here on every driver, as TypeORM also does.
+     */
     async createDb() {
         // `bun:sqlite` rejects option keys it does not know, and rejects an options object carrying no
         // open flags, so `extensions` is stripped out and what remains of it collapses back to nothing.
@@ -19,11 +24,13 @@ export class Sqlite3QuerierPool extends AbstractLocalSqliteQuerierPool {
             const { adaptBunSqlite } = await import('./bunSqliteAdapter.bun.js');
             const bunDb = new BunDatabase(this.filename, opts);
             bunDb.run('PRAGMA journal_mode = WAL');
+            bunDb.run('PRAGMA foreign_keys = ON');
             return adaptBunSqlite(bunDb);
         }
         const { default: BetterSqlite3 } = await import('better-sqlite3');
         const db = new BetterSqlite3(this.filename, opts);
         db.pragma('journal_mode = WAL');
+        db.pragma('foreign_keys = ON');
         return db;
     }
 }

package/dist/turso/tursoLocalQuerierPool.js

@@ -30,6 +30,7 @@ export class TursoLocalQuerierPool extends AbstractSqlQuerierPool {
         // Annotated rather than cast, so the structural contract is checked against the real driver.
         const db = await connect(this.filename, this.opts);
         await db.pragma('journal_mode = WAL');
+        await db.pragma('foreign_keys = ON');
         return db;
     }
     async end() {

package/dist/type/entity.d.ts

@@ -1,4 +1,4 @@
-import type { IndexType } from '../schema/types.js';
+import type { ForeignKeyAction, IndexType } from '../schema/types.js';
 import type { FilterOptions } from './query.js';
 import type { QueryRaw } from './queryRaw.js';
 import type { DistributiveOmit, Json, Scalar, Type, Unpacked } from './utility.js';
@@ -362,6 +362,20 @@ export type RelationOptions<E = any> = {
     entity: EntityGetter<E>;
     cardinality: RelationCardinality;
     readonly cascade?: boolean | CascadeType;
+    /**
+     * Referential actions for the generated foreign key, letting the database do the work instead of the
+     * ORM: `onDelete: 'CASCADE'` makes deleting the parent a single statement rather than the graph walk
+     * `cascade` performs. Defaults to the migrator's `defaultForeignKeyAction`.
+     *
+     * Read only from the side that owns the key (`@ManyToOne`, or a `@OneToOne` without `mappedBy`),
+     * matching where TypeORM, Prisma and Drizzle put it. Not available on a bare `@Field({ references })`
+     * with no relation, because `FieldOptions.onUpdate` already means a value callback there.
+     *
+     * This overlaps `cascade` rather than conflicting with it: declaring both deletes the children in JS
+     * and then leaves the foreign key nothing to cascade, so pick one.
+     */
+    readonly onDelete?: ForeignKeyAction;
+    readonly onUpdate?: ForeignKeyAction;
     mappedBy?: RelationMappedBy<E>;
     /**
      * The pivot entity of a many-to-many. Unconstrained by `E`: a pivot holds foreign keys to both
@@ -392,7 +406,7 @@ type RelationOwnerJoin<E> = Required<Pick<RelationOptions<E>, 'through'>> | Requ
  * without one of the three, resolution has no columns to join on and throws.
  */
 type RelationJoin<E> = RelationOwnerJoin<E> | Required<Pick<RelationOptions<E>, 'mappedBy'>>;
-type RelationOptionsOwner<E> = Pick<RelationOptions<E>, 'entity' | 'references' | 'cascade'>;
+type RelationOptionsOwner<E> = Pick<RelationOptions<E>, 'entity' | 'references' | 'cascade' | 'onDelete' | 'onUpdate'>;
 type RelationOptionsInverseSide<E> = Pick<RelationOptions<E>, 'entity' | 'cascade'> & Required<Pick<RelationOptions<E>, 'mappedBy'>>;
 type RelationOptionsThroughOwner<E> = Pick<RelationOptions<E>, 'entity' | 'cascade'> & RelationOwnerJoin<E>;
 /**

package/dist/type/migration.d.ts

@@ -174,22 +174,43 @@ export interface SchemaDiff {
     readonly foreignKeysToAdd?: ForeignKeySchema[];
     readonly foreignKeysToDrop?: string[];
 }
+export interface CreateSchemaOptions {
+    readonly ifNotExists?: boolean;
+    /**
+     * Restrict which tables are created, for an incremental migration adding one table to a schema that
+     * already exists. Constraints still resolve against the full entity graph.
+     */
+    readonly only?: readonly string[];
+    /**
+     * Emit the tables without their foreign keys. Only the integration fixtures want this, and only until
+     * their data stops relying on dangling references; a migration always wants the constraints.
+     */
+    readonly foreignKeys?: boolean;
+}
+export interface DropSchemaOptions {
+    readonly ifExists?: boolean;
+    readonly cascade?: boolean;
+}
 /**
  * Interface for generating DDL statements from entity metadata
  */
 export interface SchemaGenerator {
     /**
-     * DDL to create an entity’s table: one element per `querier.run` (optional `CREATE EXTENSION`, `CREATE TABLE`, each `CREATE INDEX`, …).
-     * Join with `'\n'` if you need a single script blob.
+     * The whole schema for `entities`: every table, then the foreign keys between them.
+     *
+     * There is deliberately no per-entity counterpart. One entity means an AST holding one table, so every
+     * cross-entity foreign key has nothing to resolve against and is dropped: all three call sites that
+     * used to work that way emitted schemas with no referential integrity.
      */
-    generateCreateTable<E>(entity: Type<E>, options?: {
-        ifNotExists?: boolean;
-    }): string[];
+    generateCreateSchema(entities: readonly Type<unknown>[], options?: CreateSchemaOptions): string[];
+    /**
+     * Every `DROP TABLE` for `entities`, dependents first. The inverse of {@link generateCreateSchema},
+     * and the reason it takes the whole set: dropping in any order that ignores the relation graph is
+     * rejected once the foreign keys are really there.
+     */
+    generateDropSchema(entities: readonly Type<unknown>[], options?: DropSchemaOptions): string[];
     /** Generate DROP TABLE statement. */
-    generateDropTable(tableName: string, options?: {
-        ifExists?: boolean;
-        cascade?: boolean;
-    }): string;
+    generateDropTable(tableName: string, options?: DropSchemaOptions): string;
     /**
      * Generate ALTER TABLE statements based on schema diff
      */

package/dist/type/queryAggregate.d.ts

@@ -107,6 +107,9 @@ type FieldValueType<E, F> = F extends keyof E ? E[F] : unknown;
 /**
  * Resolves a single computed column's type from its aggregate function: `$count`/`$sum`/`$avg` are
  * always `number`; `$min`/`$max` keep the aggregated field's own type.
+ *
+ * `$sum`/`$avg` are exact to 2^53: Postgres widens a sum over BIGINT to NUMERIC, and decoding that
+ * text to satisfy this `number` drops the digits past that bound. Use `raw()` for a wider total.
  * @internal
  */
 type QueryAggregateFnResult<E, Fn> = Fn extends QueryAggregateNumericFn ? number : Fn extends {

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

@@ -3,6 +3,10 @@ import type { FieldOptions } from '../type/index.js';
  * Checks if a field type is numeric (Number, BigInt, or explicit numeric logical types)
  */
 export declare function isNumericType(type: unknown): boolean;
+/**
+ * Checks if a field type is boolean (Boolean, or an explicit boolean logical type)
+ */
+export declare function isBooleanType(type: unknown): boolean;
 /**
  * Checks if a field type is JSON
  */

package/dist/util/field.util.js

@@ -31,6 +31,18 @@ export function isNumericType(type) {
     }
     return false;
 }
+/**
+ * Checks if a field type is boolean (Boolean, or an explicit boolean logical type)
+ */
+export function isBooleanType(type) {
+    if (type === Boolean)
+        return true;
+    if (typeof type === 'string') {
+        const lowered = type.toLowerCase();
+        return lowered === 'bool' || lowered === 'boolean';
+    }
+    return false;
+}
 /**
  * Checks if a field type is JSON
  */

package/dist/util/sqlLiteral.js

@@ -64,6 +64,22 @@ function createEscaper(escapeString) {
         }
         return sql;
     };
+    /** Split out so the `typeof` switch below stays a flat one-line-per-type dispatch. */
+    const escapeObject = (value) => {
+        if (value instanceof Date) {
+            return Number.isNaN(value.getTime()) ? 'NULL' : dateLiteral(value);
+        }
+        if (Array.isArray(value)) {
+            return sqlList(value);
+        }
+        if (isByteSource(value)) {
+            return bytesToHexLiteral(value);
+        }
+        if ('toSqlString' in value && typeof value.toSqlString === 'function') {
+            return String(value.toSqlString());
+        }
+        throw new TypeError('escapeSqlLiteral: plain objects are not supported; use bound parameters or JSON.stringify + a string column.');
+    };
     const escapeValue = (value) => {
         if (value === undefined || value === null) {
             return 'NULL';
@@ -77,24 +93,11 @@ function createEscaper(escapeString) {
                 return String(value);
             case 'string':
                 return escapeString(value);
+            case 'object':
+                return escapeObject(value);
             case 'symbol':
             case 'function':
                 throw new TypeError('escapeSqlLiteral: symbol and function values are not supported; use bound parameters.');
-            case 'object': {
-                if (value instanceof Date) {
-                    return Number.isNaN(value.getTime()) ? 'NULL' : dateLiteral(value);
-                }
-                if (Array.isArray(value)) {
-                    return sqlList(value);
-                }
-                if (isByteSource(value)) {
-                    return bytesToHexLiteral(value);
-                }
-                if ('toSqlString' in value && typeof value.toSqlString === 'function') {
-                    return String(value.toSqlString());
-                }
-                throw new TypeError('escapeSqlLiteral: plain objects are not supported; use bound parameters or JSON.stringify + a string column.');
-            }
             default:
                 // Unreachable today; throwing keeps a future JS type from silently becoming SQL.
                 throw new TypeError(`escapeSqlLiteral: unsupported value type '${typeof value}'; use bound parameters.`);

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://uql-orm.dev",
   "description": "Extremely fast, type-safe TypeScript ORM - one API for every database",
   "license": "MIT",
-  "version": "0.24.6",
+  "version": "0.25.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -134,18 +134,18 @@
     "@tursodatabase/serverless": "^1.4.0",
     "@types/better-sqlite3": "^9.6.0",
     "@types/express": "^5.0.6",
-    "@types/pg": "^8.20.4",
+    "@types/pg": "^8.21.0",
     "@types/ws": "^8.18.1",
     "better-sqlite3": "^13.0.3",
     "express": "^5.2.1",
     "mariadb": "^3.5.3",
     "mongodb": "^7.5.0",
     "mysql2": "^3.23.2",
-    "pg": "^8.22.0",
-    "pg-query-stream": "^4.16.0",
+    "pg": "^8.23.0",
+    "pg-query-stream": "^4.17.0",
     "rxjs": "^7.8.2",
     "sqlite-vec": "^0.1.9",
-    "ws": "^8.21.2"
+    "ws": "^8.21.3"
   },
   "author": "Roger Padilla",
   "repository": {
@@ -198,5 +198,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "2610226954cdf152705dc47ca130f6908a91825d"
+  "gitHead": "cfe2b005308b808d2e6e3d6e062c13791c883d13"
 }