uql-orm 0.24.6 → 0.24.7

package/dist/migrate/introspection/postgresIntrospector.js

@@ -3,9 +3,6 @@ import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.j
  * PostgreSQL schema introspector
  */
 export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
-    // ============================================================================
-    // SQL Queries (dialect-specific)
-    // ============================================================================
     getTableNamesQuery() {
         return /*sql*/ `
       SELECT table_name
@@ -128,12 +125,6 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
       ORDER BY kcu.ordinal_position
     `;
     }
-    // ============================================================================
-    // Internal Types
-    // ============================================================================
-    mapTableNameRow(row) {
-        return row.table_name;
-    }
     async mapColumnsResult(_read, _tableName, results) {
         return results.map((row) => ({
             name: row.column_name,
@@ -166,9 +157,6 @@ export class PostgresSchemaIntrospector extends AbstractSqlSchemaIntrospector {
             onUpdate: this.normalizeReferentialAction(row.update_rule),
         }));
     }
-    // ============================================================================
-    // PostgreSQL-specific helpers
-    // ============================================================================
     normalizeType(dataType, udtName) {
         // Handle user-defined types and arrays
         if (dataType === 'USER-DEFINED') {

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

@@ -15,6 +15,7 @@ export declare class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospec
     protected getIndexesParams(_tableName: string): unknown[];
     protected getForeignKeysParams(_tableName: string): unknown[];
     protected getPrimaryKeyParams(_tableName: string): unknown[];
+    /** `sqlite_master`, not `information_schema`, so the column is `name`. */
     protected mapTableNameRow(row: {
         name: string;
     }): string;

package/dist/migrate/introspection/sqliteIntrospector.js

@@ -3,9 +3,6 @@ import { AbstractSqlSchemaIntrospector } from './abstractSqlSchemaIntrospector.j
  * SQLite schema introspector
  */
 export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
-    // ============================================================================
-    // SQL Queries (dialect-specific)
-    // ============================================================================
     getTableNamesQuery() {
         return /*sql*/ `
       SELECT name
@@ -55,9 +52,7 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
     getPrimaryKeyParams(_tableName) {
         return [];
     }
-    // ============================================================================
-    // Row Mapping (dialect-specific)
-    // ============================================================================
+    /** `sqlite_master`, not `information_schema`, so the column is `name`. */
     mapTableNameRow(row) {
         return row.name;
     }
@@ -128,9 +123,6 @@ export class SqliteSchemaIntrospector extends AbstractSqlSchemaIntrospector {
         }
         return pkColumns.map((r) => r.name);
     }
-    // ============================================================================
-    // SQLite-specific helpers
-    // ============================================================================
     async getUniqueColumns(read, tableName) {
         const indexes = await read(this.getIndexesQuery(tableName));
         const uniqueColumns = new Set();

package/dist/migrate/migrator.d.ts

@@ -53,6 +53,14 @@ export declare class Migrator {
         to?: string;
         step?: number;
     }): Promise<MigrationResult[]>;
+    /**
+     * Narrow a run list by `to`/`step` and execute it, stopping at the first failure.
+     *
+     * Both directions do exactly this and differ only in the list they start from: `up` takes the
+     * pending migrations, `down` the executed ones reversed. Keeping the selection in one place is what
+     * makes `--to` and `--step` mean the same thing whichever way you are going.
+     */
+    private runInOrder;
     /**
      * Run a single migration within a transaction
      */

package/dist/migrate/migrator.js

@@ -130,27 +130,7 @@ export class Migrator {
      * Run all pending migrations
      */
     async up(options = {}) {
-        const pendingMigrations = await this.pending();
-        const results = [];
-        let migrationsToRun = pendingMigrations;
-        if (options.to) {
-            const toIndex = migrationsToRun.findIndex((m) => m.name === options.to);
-            if (toIndex === -1) {
-                throw new Error(`Migration '${options.to}' not found`);
-            }
-            migrationsToRun = migrationsToRun.slice(0, toIndex + 1);
-        }
-        if (options.step !== undefined) {
-            migrationsToRun = migrationsToRun.slice(0, options.step);
-        }
-        for (const migration of migrationsToRun) {
-            const result = await this.runMigration(migration, 'up');
-            results.push(result);
-            if (!result.success) {
-                break; // Stop on first failure
-            }
-        }
-        return results;
+        return this.runInOrder(await this.pending(), 'up', options);
     }
     /**
      * Rollback migrations
@@ -159,23 +139,33 @@ export class Migrator {
         const [migrations, executed] = await Promise.all([this.getMigrations(), this.storage.executed()]);
         const executedSet = new Set(executed);
         const executedMigrations = migrations.filter((m) => executedSet.has(m.name)).reverse(); // Rollback in reverse order
-        const results = [];
-        let migrationsToRun = executedMigrations;
+        return this.runInOrder(executedMigrations, 'down', options);
+    }
+    /**
+     * Narrow a run list by `to`/`step` and execute it, stopping at the first failure.
+     *
+     * Both directions do exactly this and differ only in the list they start from: `up` takes the
+     * pending migrations, `down` the executed ones reversed. Keeping the selection in one place is what
+     * makes `--to` and `--step` mean the same thing whichever way you are going.
+     */
+    async runInOrder(migrations, direction, options) {
+        let selected = migrations;
         if (options.to) {
-            const toIndex = migrationsToRun.findIndex((m) => m.name === options.to);
+            const toIndex = selected.findIndex((m) => m.name === options.to);
             if (toIndex === -1) {
                 throw new Error(`Migration '${options.to}' not found`);
             }
-            migrationsToRun = migrationsToRun.slice(0, toIndex + 1);
+            selected = selected.slice(0, toIndex + 1);
         }
         if (options.step !== undefined) {
-            migrationsToRun = migrationsToRun.slice(0, options.step);
+            selected = selected.slice(0, options.step);
         }
-        for (const migration of migrationsToRun) {
-            const result = await this.runMigration(migration, 'down');
+        const results = [];
+        for (const migration of selected) {
+            const result = await this.runMigration(migration, direction);
             results.push(result);
             if (!result.success) {
-                break; // Stop on first failure
+                break;
             }
         }
         return results;

package/dist/migrate/schemaGenerator.js

@@ -40,9 +40,6 @@ export class SqlSchemaGenerator {
     get serialPrimaryKeyType() {
         return this.dialect.serialPrimaryKey;
     }
-    // ============================================================================
-    // CanonicalType Integration (Unified Type System)
-    // ============================================================================
     /**
      * Convert FieldOptions to CanonicalType using the unified type system.
      */
@@ -52,9 +49,6 @@ export class SqlSchemaGenerator {
     canonicalTypeToSql(type) {
         return canonicalToSql(type, this.dialect);
     }
-    // ============================================================================
-    // SchemaGenerator Implementation
-    // ============================================================================
     generateCreateTable(entity, options = {}) {
         const builder = new SchemaASTBuilder(this.dialect.namingStrategy);
         const ast = builder.fromEntities([entity]);
@@ -390,9 +384,6 @@ export class SqlSchemaGenerator {
         };
         return normalize(current) === normalize(desired);
     }
-    // ============================================================================
-    // SchemaAST Support Methods
-    // ============================================================================
     generateCreateTableFromNode(table, options = {}) {
         const columns = [];
         const constraints = [];
@@ -468,9 +459,6 @@ export class SqlSchemaGenerator {
     generateCreateIndexFromNode(index, options = { ifNotExists: false }) {
         return this.generateCreateIndex(index.table.name, indexNodeToSchema(index), options);
     }
-    // ============================================================================
-    // Phase 3: Builder Operation Methods (Moved forward for unification)
-    // ============================================================================
     generateCreateTableFromDefinition(table, options = {}) {
         const tableNode = this.tableDefinitionToNode(table);
         return this.generateCreateTableFromNode(tableNode, options);

package/dist/neon/neonQuerierPool.d.ts

@@ -6,5 +6,5 @@ import { NeonQuerier } from './neonQuerier.js';
 export declare class NeonQuerierPool extends AbstractPgQuerierPool<PoolClient, NeonQuerier, NeonDialect> {
     readonly pool: Pool;
     constructor(opts: PoolConfig, extra?: ExtraOptions);
-    getQuerier(): Promise<NeonQuerier>;
+    protected buildQuerier(connect: () => Promise<PoolClient>): NeonQuerier;
 }

package/dist/neon/neonQuerierPool.js

@@ -1,12 +1,14 @@
-import { Pool } from '@neondatabase/serverless';
+import { Pool, types } from '@neondatabase/serverless';
 import { AbstractPgQuerierPool } from '../postgres/abstractPgQuerierPool.js';
+import { numericTypes } from '../postgres/pgNumericTypes.js';
 import { NeonDialect } from './neonDialect.js';
 import { NeonQuerier } from './neonQuerier.js';
 export class NeonQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
-        super(new NeonDialect({ namingStrategy: extra?.namingStrategy }), new Pool(opts), extra);
+        // Neon's own `types`, not `pg`'s: this entry has to load on an edge runtime where `pg` is absent.
+        super(new NeonDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ types: numericTypes(types), ...opts }), extra);
     }
-    async getQuerier() {
-        return new NeonQuerier(() => this.pool.connect(), this.dialect, this.extra);
+    buildQuerier(connect) {
+        return new NeonQuerier(connect, this.dialect, this.extra);
     }
 }

package/dist/postgres/abstractPgQuerierPool.d.ts

@@ -17,5 +17,11 @@ export interface PgAnyPool<C extends PgAnyClient> extends ErrorEmittingPool {
 export declare abstract class AbstractPgQuerierPool<C extends PgAnyClient, Q extends AbstractPgQuerier<C, D>, D extends AbstractSqlDialect> extends AbstractSqlQuerierPool<Q, D> {
     readonly pool: PgAnyPool<C>;
     constructor(dialect: D, pool: PgAnyPool<C>, extra?: ExtraOptions);
+    /**
+     * Every pg-compatible pool acquires a client the same way, so only the querier class varies.
+     * Subclasses name that instead of restating the lazy `connect` the querier expects.
+     */
+    protected abstract buildQuerier(connect: () => Promise<C>): Q;
+    getQuerier(): Promise<Q>;
     end(): Promise<void>;
 }

package/dist/postgres/abstractPgQuerierPool.js

@@ -14,6 +14,9 @@ export class AbstractPgQuerierPool extends AbstractSqlQuerierPool {
         this.pool = pool;
         attachPoolErrorHandler(pool, 'Idle Postgres pool client encountered an error');
     }
+    async getQuerier() {
+        return this.buildQuerier(() => this.pool.connect());
+    }
     async end() {
         await this.pool.end();
     }

package/dist/postgres/pgNumericTypes.d.ts

@@ -0,0 +1,41 @@
+import type { CustomTypesConfig } from 'pg';
+/**
+ * The shape every pg-family driver exposes as `types`: `pg`'s own, and `@neondatabase/serverless`'s
+ * reimplementation of it. Taken as a parameter rather than imported, because `uql-orm/neon` must not
+ * pull `pg` into an edge bundle that has no such peer installed - the same reason
+ * `abstractPgQuerierPool.ts` keeps its `pg` imports type-only.
+ */
+type PgTypes = {
+    readonly builtins: Readonly<Record<string, number>>;
+    getTypeParser(oid: number, format?: 'text' | 'binary'): (value: string) => unknown;
+};
+/**
+ * Decode `INT8` and `FLOAT8` as JS numbers, leaving every other type to the driver.
+ *
+ * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
+ * `schema/canonicalType.ts`), so without it a field declared `number` read back as `'9'` - including
+ * every auto-increment primary key, on every entity. `FLOAT8` is a float64, which is exactly what a
+ * JS number is, so decoding it loses nothing at all.
+ *
+ * At the driver because everything crosses the wire decoder exactly once - entity reads, `RETURNING
+ * id`, raw SQL, counts, aggregates - while the ORM's hydration only ever sees entity reads. Which
+ * types belong here and which need the entity's declaration is settled in `hydratableFields`.
+ *
+ * `NUMERIC` is deliberately absent, and decoded in hydration instead: `type: BigInt` also maps to
+ * BIGINT, so a blanket decode here is already as far as a driver can go without the declaration. That
+ * split also covers mysql2, which returns DECIMAL as text and has no equivalent hook.
+ *
+ * Per pool, never global, which is the whole reason this takes `types` as an argument. TypeORM does
+ * the same job by assigning `postgres.defaults.parseInt8`, a module-wide flag every pool in the
+ * process then shares; MikroORM passes a per-pool `TypeOverrides`, as here. Two globals of exactly
+ * that shape have already been deleted from this repo - `test/pgTypeParsers.util.ts` and the
+ * `types.setTypeParser` calls in `neon/neonQuerier.test.ts` - and both made the suite pass on
+ * behaviour the library never shipped. Do not reintroduce one.
+ *
+ * Exact to 2^53, which covers any auto-increment id. A caller who needs more passes their own
+ * `types` in the pool options: it is spread after this one and therefore wins. For a decimal, the
+ * lighter escape hatch is the declaration itself: `@Field({ type: String, columnType: 'decimal' })`
+ * keeps the column DECIMAL while leaving the value as the exact text the driver returned.
+ */
+export declare function numericTypes(types: PgTypes): CustomTypesConfig;
+export {};

package/dist/postgres/pgNumericTypes.js

@@ -0,0 +1,35 @@
+/**
+ * Decode `INT8` and `FLOAT8` as JS numbers, leaving every other type to the driver.
+ *
+ * uql owes this to the caller because uql picks the column: `type: Number` maps to BIGINT (see
+ * `schema/canonicalType.ts`), so without it a field declared `number` read back as `'9'` - including
+ * every auto-increment primary key, on every entity. `FLOAT8` is a float64, which is exactly what a
+ * JS number is, so decoding it loses nothing at all.
+ *
+ * At the driver because everything crosses the wire decoder exactly once - entity reads, `RETURNING
+ * id`, raw SQL, counts, aggregates - while the ORM's hydration only ever sees entity reads. Which
+ * types belong here and which need the entity's declaration is settled in `hydratableFields`.
+ *
+ * `NUMERIC` is deliberately absent, and decoded in hydration instead: `type: BigInt` also maps to
+ * BIGINT, so a blanket decode here is already as far as a driver can go without the declaration. That
+ * split also covers mysql2, which returns DECIMAL as text and has no equivalent hook.
+ *
+ * Per pool, never global, which is the whole reason this takes `types` as an argument. TypeORM does
+ * the same job by assigning `postgres.defaults.parseInt8`, a module-wide flag every pool in the
+ * process then shares; MikroORM passes a per-pool `TypeOverrides`, as here. Two globals of exactly
+ * that shape have already been deleted from this repo - `test/pgTypeParsers.util.ts` and the
+ * `types.setTypeParser` calls in `neon/neonQuerier.test.ts` - and both made the suite pass on
+ * behaviour the library never shipped. Do not reintroduce one.
+ *
+ * Exact to 2^53, which covers any auto-increment id. A caller who needs more passes their own
+ * `types` in the pool options: it is spread after this one and therefore wins. For a decimal, the
+ * lighter escape hatch is the declaration itself: `@Field({ type: String, columnType: 'decimal' })`
+ * keeps the column DECIMAL while leaving the value as the exact text the driver returned.
+ */
+export function numericTypes(types) {
+    // Text only: in binary mode an INT8 arrives as an 8-byte Buffer, and `Number(buffer)` is `NaN`.
+    const textNumeric = new Set([types.builtins['INT8'], types.builtins['FLOAT8']]);
+    return {
+        getTypeParser: (oid, format) => format === 'text' && textNumeric.has(oid) ? Number : types.getTypeParser(oid, format),
+    };
+}

package/dist/postgres/pgQuerierPool.d.ts

@@ -6,5 +6,5 @@ import { PgQuerier } from './pgQuerier.js';
 export declare class PgQuerierPool extends AbstractPgQuerierPool<PoolClient, PgQuerier, PgDialect> {
     readonly pool: Pool;
     constructor(opts: PoolConfig, extra?: ExtraOptions);
-    getQuerier(): Promise<PgQuerier>;
+    protected buildQuerier(connect: () => Promise<PoolClient>): PgQuerier;
 }

package/dist/postgres/pgQuerierPool.js

@@ -1,14 +1,15 @@
-import { Pool } from 'pg';
+import { Pool, types } from 'pg';
 import { AbstractPgQuerierPool } from './abstractPgQuerierPool.js';
 import { PgDialect } from './pgDialect.js';
+import { numericTypes } from './pgNumericTypes.js';
 import { PgQuerier } from './pgQuerier.js';
 export class PgQuerierPool extends AbstractPgQuerierPool {
     constructor(opts, extra) {
         // keepAlive reduces (but can't eliminate) idle connections being silently
         // dropped by NATs/firewalls on long-lived remote connections.
-        super(new PgDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ keepAlive: true, ...opts }), extra);
+        super(new PgDialect({ namingStrategy: extra?.namingStrategy }), new Pool({ keepAlive: true, types: numericTypes(types), ...opts }), extra);
     }
-    async getQuerier() {
-        return new PgQuerier(() => this.pool.connect(), this.dialect, this.extra);
+    buildQuerier(connect) {
+        return new PgQuerier(connect, this.dialect, this.extra);
     }
 }

package/dist/querier/abstractSqlQuerier.d.ts

@@ -41,8 +41,15 @@ export declare abstract class AbstractSqlQuerier extends AbstractQuerier impleme
      * Drivers with native cursor/streaming APIs (SQLite, Pg) should override this.
      */
     protected internalStream<T>(query: string, values?: unknown[]): AsyncIterable<T>;
-    private hydrateJsonFields;
-    private hydrateJsonFieldsRecursive;
+    /**
+     * 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.
+     */
+    private hydrateFields;
     protected internalCount<E extends object>(entity: Type<E>, q?: QuerySearch<E>, opts?: QueryOptions): Promise<number>;
     protected internalAggregate<E extends object, G extends QueryGroupMap<E>, A extends QueryAggMap<E>>(entity: Type<E>, q: QueryAggregate<E, G, A>, opts?: QueryOptions): Promise<QueryAggregateResult<E, G, A>[]>;
     internalInsertMany<E extends object>(entity: Type<E>, payload: E[]): Promise<IdValue<E>[]>;

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) {

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.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.)
      */

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
  */