uql-orm 0.24.5 → 0.24.7

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/query.d.ts

@@ -172,6 +172,8 @@ export type Query<E> = {
     $populate?: QueryPopulate<E>;
     /**
      * field exclusion - `{ name: true }` blacklists fields. Mutually exclusive with positive `$select`.
+     * Keys a relation is assembled from (a joined row's primary key, a to-many's foreign key) are kept
+     * regardless, since subtracting them would leave the relation unfilled.
      */
     $exclude?: QueryExclude<E>;
     /**

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.5",
+  "version": "0.24.7",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -134,9 +134,9 @@
     "@tursodatabase/serverless": "^1.4.0",
     "@types/better-sqlite3": "^9.6.0",
     "@types/express": "^5.0.6",
-    "@types/pg": "^8.20.3",
+    "@types/pg": "^8.21.0",
     "@types/ws": "^8.18.1",
-    "better-sqlite3": "^13.0.2",
+    "better-sqlite3": "^13.0.3",
     "express": "^5.2.1",
     "mariadb": "^3.5.3",
     "mongodb": "^7.5.0",
@@ -145,7 +145,7 @@
     "pg-query-stream": "^4.16.0",
     "rxjs": "^7.8.2",
     "sqlite-vec": "^0.1.9",
-    "ws": "^8.21.1"
+    "ws": "^8.21.3"
   },
   "author": "Roger Padilla",
   "repository": {
@@ -198,5 +198,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "1c763ccfdb4431afa49716b99512d9df4e0ad4b7"
+  "gitHead": "26ffc7e2968761bc95a0bb1ffe0aeb37600ba1f1"
 }