@uql/core 3.1.3 → 3.3.0

package/CHANGELOG.md

@@ -3,13 +3,9 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [3.1.3](https://github.com/rogerpadilla/uql/compare/@uql/core@3.1.2...@uql/core@3.1.3) (2025-12-30)
+# [3.3.0](https://github.com/rogerpadilla/uql/compare/@uql/core@3.2.0...@uql/core@3.3.0) (2025-12-30)
 
-
-### Features
-
-* add migration CLI and update core package build configuration with new build config and declaration maps while removing old path aliases. ([2b87dd4](https://github.com/rogerpadilla/uql/commit/2b87dd411d05c9844b3e3a6b0a7c74d120b9c362))
-* Implement custom test coverage reporting and simplify README database adapter table. ([837fadf](https://github.com/rogerpadilla/uql/commit/837fadf2cfc27be3a16efc2c489f83c047cc24e1))
+**Note:** Version bump only for package @uql/core
 
 
 
@@ -196,7 +192,7 @@ Reflect major changes in the package structure and dependencies.
 - Update dependencies.
 
   ```ts
-  const ids = await querierPool.transaction(async (querier) => {
+  const ids = await pool.transaction(async (querier) => {
     const data = await querier.findMany(...);
     const ids = await querier.insertMany(...);
     return ids;

package/README.md

@@ -23,7 +23,7 @@ const companyUsers = await userRepository.findMany({
 
  
 
-## Why uql?
+## Why UQL?
 
 See [this article](https://medium.com/@rogerpadillac/in-search-of-the-perfect-orm-e01fcc9bce3d) in medium.com.
 
@@ -92,11 +92,12 @@ bun add pg
 Annotate your classes with decorators from `@uql/core`. UQL supports detailed schema metadata for precise DDL generation.
 
 ```ts
+import { v7 as uuidv7 } from 'uuid';
 import { Entity, Id, Field, OneToOne, OneToMany, ManyToOne, ManyToMany, type Relation } from '@uql/core';
 
 @Entity()
 export class User {
-  @Id()
+  @Id({ onInsert: () => uuidv7() })
   id?: string;
 
   @Field({ length: 100, index: true })
@@ -114,7 +115,7 @@ export class User {
 
 @Entity()
 export class Profile {
-  @Id()
+  @Id({ onInsert: () => uuidv7() })
   id?: string;
 
   @Field()
@@ -147,7 +148,7 @@ export class Post {
 
 @Entity()
 export class Tag {
-  @Id()
+  @Id({ onInsert: () => uuidv7() })
   id?: string;
 
   @Field()
@@ -156,7 +157,7 @@ export class Tag {
 
 @Entity()
 export class PostTag {
-  @Id()
+  @Id({ onInsert: () => uuidv7() })
   id?: string;
 
   @Field({ reference: () => Post })
@@ -178,7 +179,7 @@ A querier-pool can be set in any of the bootstrap files of your app (e.g. in the
 import { SnakeCaseNamingStrategy } from '@uql/core';
 import { PgQuerierPool } from '@uql/core/postgres';
 
-export const querierPool = new PgQuerierPool(
+export const pool = new PgQuerierPool(
   {
     host: 'localhost',
     user: 'theUser',
@@ -211,10 +212,10 @@ Repositories provide a clean, Data-Mapper style interface for your entities.
 ```ts
 import { GenericRepository } from '@uql/core';
 import { User } from './shared/models/index.js';
-import { querierPool } from './shared/orm.js';
+import { pool } from './shared/orm.js';
 
 // Get a querier from the pool
-const querier = await querierPool.getQuerier();
+const querier = await pool.getQuerier();
 
 try {
   const userRepository = new GenericRepository(User, querier);
@@ -246,10 +247,10 @@ UQL's query syntax is context-aware. When you query a relation, the available fi
 
 ```ts
 import { GenericRepository } from '@uql/core';
-import { querierPool } from './shared/orm.js';
+import { pool } from './shared/orm.js';
 import { User } from './shared/models/index.js';
 
-const authorsWithPopularPosts = await querierPool.transaction(async (querier) => {
+const authorsWithPopularPosts = await pool.transaction(async (querier) => {
   const userRepository = new GenericRepository(User, querier);
 
   return userRepository.findMany({
@@ -282,6 +283,7 @@ const authorsWithPopularPosts = await querierPool.transaction(async (querier) =>
 Define complex logic directly in your entities using `raw` functions from `uql/util`. These are highly efficient as they are resolved during SQL generation.
 
 ```ts
+import { v7 as uuidv7 } from 'uuid';
 import { Entity, Id, Field, raw } from '@uql/core';
 import { ItemTag } from './shared/models/index.js';
 
@@ -313,10 +315,10 @@ export class Item {
 UQL ensures your operations are serialized and thread-safe.
 
 ```ts
-import { querierPool } from './shared/orm.js';
+import { pool } from './shared/orm.js';
 import { User, Profile } from './shared/models/index.js';
 
-const result = await querierPool.transaction(async (querier) => {
+const result = await pool.transaction(async (querier) => {
   const user = await querier.findOne(User, { $where: { email: '...' } });
   const profileId = await querier.insertOne(Profile, { userId: user.id, ... });
   return { userId: user.id, profileId };
@@ -339,7 +341,7 @@ import { PgQuerierPool } from '@uql/core/postgres';
 import { User, Post } from './shared/models/index.js';
 
 export default {
-  querierPool: new PgQuerierPool({ /* config */ }),
+  pool: new PgQuerierPool({ /* config */ }),
   entities: [User, Post],
   migrationsPath: './migrations',
 };
@@ -377,9 +379,9 @@ In development, you can use `autoSync` to automatically keep your database in sy
 
 ```ts
 import { Migrator } from '@uql/core/migrate';
-import { querierPool } from './shared/orm.js';
+import { pool } from './shared/orm.js';
 
-const migrator = new Migrator(querierPool);
+const migrator = new Migrator(pool);
 await migrator.autoSync({ logging: true });
 ```
 
@@ -406,3 +408,13 @@ For those who want to see the "engine under the hood," check out these resources
   - [PostgreSQL Spec](https://github.com/rogerpadilla/uql/blob/main/packages/core/src/postgres/postgresDialect.spec.ts) | [MySQL Spec](https://github.com/rogerpadilla/uql/blob/main/packages/core/src/mysql/mysqlDialect.spec.ts) | [SQLite Spec](https://github.com/rogerpadilla/uql/blob/main/packages/core/src/sqlite/sqliteDialect.spec.ts).
   - [Querier Integration Tests](https://github.com/rogerpadilla/uql/blob/main/packages/core/src/querier/abstractSqlQuerier-spec.ts): Testing the interaction between SQL generation and connection management.
   - [MongoDB Migration Tests](https://github.com/rogerpadilla/uql/blob/main/packages/core/src/migrate/migrator-mongo.it.ts): Integration tests ensuring correct collection and index synchronization for MongoDB.
+
+---
+
+## Built with ❤️ and supported by
+
+UQL is an open-source project driven by the community and proudly sponsored by **[Variability.ai](https://variability.ai)**.
+
+> "Intelligence in Every Fluctuation"
+
+Their support helps us maintain and evolve the "Smartest ORM" for developers everywhere. Thank you for being part of our journey!

package/dist/browser/uql-browser.min.js

@@ -1,97 +1,108 @@
-import { isSqlQuerier } from '../type/index.js';
-export { isSqlQuerier } from '../type/index.js';
-import { AbstractDialect } from '../dialect/index.js';
-import { getMeta, getEntities } from '../entity/index.js';
-import { escapeSqlId, getKeys } from '../util/index.js';
-import { readdir, readFile, mkdir, writeFile } from 'node:fs/promises';
-import { join, basename, extname, dirname } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import sqlstring from 'sqlstring-sqlite';
+import { AbstractSqlDialect } from '../dialect/index.js';
+import { getMeta } from '../entity/index.js';
+import { AbstractSqlQuerier, AbstractQuerierPool } from '../querier/index.js';
 
-/**
- * Abstract base class for SQL schema generation
- */ class AbstractSchemaGenerator extends AbstractDialect {
-    constructor(namingStrategy, escapeIdChar = '`'){
-        super(namingStrategy), this.escapeIdChar = escapeIdChar;
+class SqliteDialect extends AbstractSqlDialect {
+    constructor(namingStrategy){
+        super(namingStrategy, '`', 'BEGIN TRANSACTION');
     }
-    /**
-   * Escape an identifier (table name, column name, etc.)
-   */ escapeId(identifier) {
-        return escapeSqlId(identifier, this.escapeIdChar);
+    addValue(values, value) {
+        if (value instanceof Date) {
+            value = value.getTime();
+        } else if (typeof value === 'boolean') {
+            value = value ? 1 : 0;
+        }
+        return super.addValue(values, value);
     }
-    generateCreateTable(entity, options = {}) {
-        const meta = getMeta(entity);
-        const tableName = this.resolveTableName(entity, meta);
-        const columns = this.generateColumnDefinitions(meta);
-        const constraints = this.generateTableConstraints(meta);
-        const ifNotExists = options.ifNotExists ? 'IF NOT EXISTS ' : '';
-        let sql = `CREATE TABLE ${ifNotExists}${this.escapeId(tableName)} (\n`;
-        sql += columns.map((col)=>`  ${col}`).join(',\n');
-        if (constraints.length > 0) {
-            sql += ',\n';
-            sql += constraints.map((c)=>`  ${c}`).join(',\n');
-        }
-        sql += '\n)';
-        sql += this.getTableOptions(meta);
-        sql += ';';
-        return sql;
+    compare(ctx, entity, key, val, opts) {
+        if (key === '$text') {
+            const meta = getMeta(entity);
+            const search = val;
+            const fields = search.$fields.map((fKey)=>{
+                const field = meta.fields[fKey];
+                const columnName = this.resolveColumnName(fKey, field);
+                return this.escapeId(columnName);
+            });
+            const tableName = this.resolveTableName(entity, meta);
+            ctx.append(`${this.escapeId(tableName)} MATCH {${fields.join(' ')}} : `);
+            ctx.addValue(search.$value);
+            return;
+        }
+        super.compare(ctx, entity, key, val, opts);
     }
-    generateDropTable(entity) {
+    compareFieldOperator(ctx, entity, key, op, val, opts = {}) {
+        super.compareFieldOperator(ctx, entity, key, op, val, opts);
+    }
+    upsert(ctx, entity, conflictPaths, payload) {
         const meta = getMeta(entity);
-        const tableName = this.resolveTableName(entity, meta);
-        return `DROP TABLE IF EXISTS ${this.escapeId(tableName)};`;
+        const update = this.getUpsertUpdateAssignments(ctx, meta, conflictPaths, payload, (name)=>`EXCLUDED.${name}`);
+        const keysStr = this.getUpsertConflictPathsStr(meta, conflictPaths);
+        const onConflict = update ? `DO UPDATE SET ${update}` : 'DO NOTHING';
+        this.insert(ctx, entity, payload);
+        ctx.append(` ON CONFLICT (${keysStr}) ${onConflict}`);
     }
-    generateAlterTable(diff) {
-        const statements = [];
-        const tableName = this.escapeId(diff.tableName);
-        // Add new columns
-        if (diff.columnsToAdd?.length) {
-            for (const column of diff.columnsToAdd){
-                const colDef = this.generateColumnDefinitionFromSchema(column);
-                statements.push(`ALTER TABLE ${tableName} ADD COLUMN ${colDef};`);
-            }
-        }
-        // Alter existing columns
-        if (diff.columnsToAlter?.length) {
-            for (const { to } of diff.columnsToAlter){
-                const colDef = this.generateColumnDefinitionFromSchema(to);
-                const colStatements = this.generateAlterColumnStatements(diff.tableName, to, colDef);
-                statements.push(...colStatements);
-            }
-        }
-        // Drop columns
-        if (diff.columnsToDrop?.length) {
-            for (const columnName of diff.columnsToDrop){
-                statements.push(`ALTER TABLE ${tableName} DROP COLUMN ${this.escapeId(columnName)};`);
-            }
-        }
-        // Add indexes
-        if (diff.indexesToAdd?.length) {
-            for (const index of diff.indexesToAdd){
-                statements.push(this.generateCreateIndex(diff.tableName, index));
-            }
-        }
-        // Drop indexes
-        if (diff.indexesToDrop?.length) {
-            for (const indexName of diff.indexesToDrop){
-                statements.push(this.generateDropIndex(diff.tableName, indexName));
-            }
+    escape(value) {
+        return sqlstring.escape(value);
+    }
+}
+
+class SqliteQuerier extends AbstractSqlQuerier {
+    constructor(db, extra){
+        super(new SqliteDialect(extra?.namingStrategy)), this.db = db, this.extra = extra;
+    }
+    async internalAll(query, values) {
+        this.extra?.logger?.(query, values);
+        return this.db.prepare(query).all(values || []);
+    }
+    async internalRun(query, values) {
+        this.extra?.logger?.(query, values);
+        const { changes, lastInsertRowid } = this.db.prepare(query).run(values || []);
+        const firstId = lastInsertRowid ? Number(lastInsertRowid) - (changes - 1) : undefined;
+        const ids = firstId ? Array(changes).fill(firstId).map((i, index)=>i + index) : [];
+        return {
+            changes,
+            ids,
+            firstId
+        };
+    }
+    async internalRelease() {
+        if (this.hasOpenTransaction) {
+            throw TypeError('pending transaction');
         }
-        return statements;
+    // no-op
     }
-    generateAlterTableDown(diff) {
-        const statements = [];
-        const tableName = this.escapeId(diff.tableName);
-        // Rollback additions by dropping columns
-        if (diff.columnsToAdd?.length) {
-            for (const column of diff.columnsToAdd){
-                statements.push(`ALTER TABLE ${tableName} DROP COLUMN ${this.escapeId(column.name)};`);
+}
+
+class Sqlite3QuerierPool extends AbstractQuerierPool {
+    constructor(filename, opts, extra){
+        super('sqlite', extra), this.filename = filename, this.opts = opts;
+    }
+    async getQuerier() {
+        if (!this.querier) {
+            let db;
+            if (typeof Bun !== 'undefined') {
+                const { Database } = await import('bun:sqlite');
+                db = new Database(this.filename, this.opts);
+                db.run('PRAGMA journal_mode = WAL');
+            } else {
+                const { default: Database } = await import('better-sqlite3');
+                db = new Database(this.filename, this.opts);
+                db.pragma('journal_mode = WAL');
             }
+            this.querier = new SqliteQuerier(db, this.extra);
         }
-        return statements;
+        return this.querier;
     }
-    generateCreateIndex(tableName, index) {
-        const unique = index.unique ? 'UNIQUE ' : '';
-        const columns = index.columns.map((c)=>this.escapeId(c)).join(', ');
+    async end() {
+        await this.querier.db.close();
+        delete this.querier;
+    }
+}
+
+export { Sqlite3QuerierPool, SqliteDialect, SqliteQuerier };
+//# sourceMappingURL=uql-browser.min.js.map
+>this.escapeId(c)).join(', ');
         return `CREATE ${unique}INDEX ${this.escapeId(index.name)} ON ${this.escapeId(tableName)} (${columns});`;
     }
     generateDropIndex(tableName, indexName) {
@@ -609,8 +620,8 @@ import { pathToFileURL } from 'node:url';
  * MySQL/MariaDB schema introspector.
  * Works with both MySQL and MariaDB as they share the same information_schema structure.
  */ class MysqlSchemaIntrospector {
-    constructor(querierPool){
-        this.querierPool = querierPool;
+    constructor(pool){
+        this.pool = pool;
     }
     async getTableSchema(tableName) {
         const querier = await this.getQuerier();
@@ -673,7 +684,7 @@ import { pathToFileURL } from 'node:url';
         return (results[0]?.count ?? 0) > 0;
     }
     async getQuerier() {
-        const querier = await this.querierPool.getQuerier();
+        const querier = await this.pool.getQuerier();
         if (!isSqlQuerier(querier)) {
             await querier.release();
             throw new Error('MysqlSchemaIntrospector requires a SQL-based querier');
@@ -831,8 +842,8 @@ import { pathToFileURL } from 'node:url';
 /**
  * PostgreSQL schema introspector
  */ class PostgresSchemaIntrospector {
-    constructor(querierPool){
-        this.querierPool = querierPool;
+    constructor(pool){
+        this.pool = pool;
     }
     async getTableSchema(tableName) {
         const querier = await this.getQuerier();
@@ -896,7 +907,7 @@ import { pathToFileURL } from 'node:url';
         return results[0]?.exists ?? false;
     }
     async getQuerier() {
-        const querier = await this.querierPool.getQuerier();
+        const querier = await this.pool.getQuerier();
         if (!isSqlQuerier(querier)) {
             await querier.release();
             throw new Error('PostgresSchemaIntrospector requires a SQL-based querier');
@@ -1104,8 +1115,8 @@ import { pathToFileURL } from 'node:url';
 /**
  * SQLite schema introspector
  */ class SqliteSchemaIntrospector {
-    constructor(querierPool){
-        this.querierPool = querierPool;
+    constructor(pool){
+        this.pool = pool;
     }
     async getTableSchema(tableName) {
         const querier = await this.getQuerier();
@@ -1168,7 +1179,7 @@ import { pathToFileURL } from 'node:url';
         return (results[0]?.count ?? 0) > 0;
     }
     async getQuerier() {
-        const querier = await this.querierPool.getQuerier();
+        const querier = await this.pool.getQuerier();
         if (!isSqlQuerier(querier)) {
             await querier.release();
             throw new Error('SqliteSchemaIntrospector requires a SQL-based querier');
@@ -1425,11 +1436,11 @@ class MongoSchemaGenerator extends AbstractDialect {
 }
 
 class MongoSchemaIntrospector {
-    constructor(querierPool){
-        this.querierPool = querierPool;
+    constructor(pool){
+        this.pool = pool;
     }
     async getTableSchema(tableName) {
-        const querier = await this.querierPool.getQuerier();
+        const querier = await this.pool.getQuerier();
         try {
             const { db } = querier;
             const collections = await db.listCollections({
@@ -1454,7 +1465,7 @@ class MongoSchemaIntrospector {
         }
     }
     async getTableNames() {
-        const querier = await this.querierPool.getQuerier();
+        const querier = await this.pool.getQuerier();
         try {
             const { db } = querier;
             const collections = await db.listCollections().toArray();
@@ -1473,8 +1484,8 @@ class MongoSchemaIntrospector {
  * Stores migration state in a database table.
  * Uses the querier's dialect for escaping and placeholders.
  */ class DatabaseMigrationStorage {
-    constructor(querierPool, options = {}){
-        this.querierPool = querierPool;
+    constructor(pool, options = {}){
+        this.pool = pool;
         this.storageInitialized = false;
         this.tableName = options.tableName ?? 'uql_migrations';
     }
@@ -1482,7 +1493,7 @@ class MongoSchemaIntrospector {
         if (this.storageInitialized) {
             return;
         }
-        const querier = await this.querierPool.getQuerier();
+        const querier = await this.pool.getQuerier();
         if (!isSqlQuerier(querier)) {
             await querier.release();
             throw new Error('DatabaseMigrationStorage requires a SQL-based querier');
@@ -1506,7 +1517,7 @@ class MongoSchemaIntrospector {
     }
     async executed() {
         await this.ensureStorage();
-        const querier = await this.querierPool.getQuerier();
+        const querier = await this.pool.getQuerier();
         if (!isSqlQuerier(querier)) {
             await querier.release();
             throw new Error('DatabaseMigrationStorage requires a SQL-based querier');
@@ -1545,10 +1556,10 @@ class MongoSchemaIntrospector {
 /**
  * Main class for managing database migrations
  */ class Migrator {
-    constructor(querierPool, options = {}){
-        this.querierPool = querierPool;
-        this.dialect = options.dialect ?? querierPool.dialect ?? 'postgres';
-        this.storage = options.storage ?? new DatabaseMigrationStorage(querierPool, {
+    constructor(pool, options = {}){
+        this.pool = pool;
+        this.dialect = options.dialect ?? pool.dialect ?? 'postgres';
+        this.storage = options.storage ?? new DatabaseMigrationStorage(pool, {
             tableName: options.tableName
         });
         this.migrationsPath = options.migrationsPath ?? './migrations';
@@ -1565,15 +1576,15 @@ class MongoSchemaIntrospector {
     createIntrospector() {
         switch(this.dialect){
             case 'postgres':
-                return new PostgresSchemaIntrospector(this.querierPool);
+                return new PostgresSchemaIntrospector(this.pool);
             case 'mysql':
-                return new MysqlSchemaIntrospector(this.querierPool);
+                return new MysqlSchemaIntrospector(this.pool);
             case 'mariadb':
-                return new MariadbSchemaIntrospector(this.querierPool);
+                return new MariadbSchemaIntrospector(this.pool);
             case 'sqlite':
-                return new SqliteSchemaIntrospector(this.querierPool);
+                return new SqliteSchemaIntrospector(this.pool);
             case 'mongodb':
-                return new MongoSchemaIntrospector(this.querierPool);
+                return new MongoSchemaIntrospector(this.pool);
             default:
                 return undefined;
         }
@@ -1687,7 +1698,7 @@ class MongoSchemaIntrospector {
    * Run a single migration within a transaction
    */ async runMigration(migration, direction) {
         const startTime = Date.now();
-        const querier = await this.querierPool.getQuerier();
+        const querier = await this.pool.getQuerier();
         if (!isSqlQuerier(querier)) {
             await querier.release();
             throw new Error('Migrator requires a SQL-based querier');
@@ -1829,7 +1840,7 @@ class MongoSchemaIntrospector {
             throw new Error('Schema generator not set. Call setSchemaGenerator() first.');
         }
         const entities = this.entities.length > 0 ? this.entities : getEntities();
-        const querier = await this.querierPool.getQuerier();
+        const querier = await this.pool.getQuerier();
         if (!isSqlQuerier(querier)) {
             await querier.release();
             throw new Error('Migrator requires a SQL-based querier');
@@ -1901,7 +1912,7 @@ class MongoSchemaIntrospector {
         return filteredDiff;
     }
     async executeSyncStatements(statements, options) {
-        const querier = await this.querierPool.getQuerier();
+        const querier = await this.pool.getQuerier();
         try {
             if (this.dialect === 'mongodb') {
                 await this.executeMongoSyncStatements(statements, options, querier);