@uql/core 3.7.13 → 3.8.1

package/CHANGELOG.md

@@ -3,7 +3,7 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [3.7.13](https://github.com/rogerpadilla/uql/compare/@uql/core@3.7.12...@uql/core@3.7.13) (2026-01-07)
+## [3.8.1](https://github.com/rogerpadilla/uql/compare/@uql/core@3.8.0...@uql/core@3.8.1) (2026-01-08)
 
 **Note:** Version bump only for package @uql/core
 
@@ -17,7 +17,16 @@ All notable changes to this project will be documented in this file. Please add
 
 date format is [yyyy-mm-dd]
 
-## [3.7.13] - 2026-01-06
+## [3.8.0] - 2026-01-08
+### Schema Sync System & AST Engine
+- **Schema AST Feature**: Introduced a revolutionary **Schema AST (Abstract Syntax Tree)** engine that treats the database schema as a graph. This enables features like **Circular Dependency Detection** and automatic topological sorting for `CREATE`/`DROP` operations, solving complex schema edge cases that simple list-based approaches cannot handle.
+- **Smart Relation Detection**: When scaffolding entities from an existing database (`generate:from-db`), UQL now automatically infers **OneToOne** and **ManyToMany** relationships by analyzing foreign key structures and naming conventions (e.g., `user_id` -> `User` entity), significantly reducing manual boilerplate.
+- **Drift Detection**: Added the `drift:check` command to detect discrepancies between your TypeScript entities and the actual database schema. It reports critical issues (missing tables, risk of data truncation) and warnings (missing indexes) to ensure production safety.
+- **Bidirectional Index Sync**: Indexes are now fully synchronized in both directions. `@Field({ index: true })` definitions are pushed to the database, and existing database indexes are reflected in generated entity files.
+- **Unified Migration Builder API**: Refactored the migration builder to use a cohesive **Options Object** API (e.g., `t.string('email', { length: 255, unique: true })`). This replaces the old positional argument style, aligning strictly with the `@Field` decorator options for a consistent developer experience.
+- **Refactored Generators**: Consolidated `SqlSchemaGenerator` and `MongoSchemaGenerator` into a unified architecture, sharing core logic for simpler maintenance and better type safety.
+
+## [3.7.14] - 2026-01-06
 ### Documentation
 - **README Refinement**: Improved docs about new Migrations feature.
 

package/README.md

@@ -40,12 +40,13 @@ const users = await querier.findMany(User, {
 | **[Context-Aware Queries](https://uql.app/querying/relations)**       | Deep type-safety for operators and [relations](https://uql.app/querying/relations) at any depth.                                    |
 | **Serializable JSON**                                              | 100% valid JSON queries for easy transport over HTTP/Websockets.                                                                |
 | **Unified Dialects**                                               | Write once, run anywhere: PostgreSQL, MySQL, SQLite, MongoDB, and more.                                                         |
-| **Naming Strategies**                                              | Pluggable system to translate between TypeScript `camelCase` and database `snake_case`.                                     |
+| **[Naming Strategies](https://uql.app/naming-strategy)**           | Pluggable system to translate between TypeScript `camelCase` and database `snake_case`.                                     |
 | **Smart SQL Engine**                                               | Optimized sub-queries, placeholders ($1, $2), and minimal SQL generation via `QueryContext`.                                  |
 | **Thread-Safe by Design**                                          | Centralized task queue and `@Serialized()` decorator prevent race conditions.                                                 |
-| **Declarative Transactions**                                       | Standard `@Transactional()` and `@InjectQuerier()` decorators for NestJS/DI.                                                |
+| **[Declarative Transactions](https://www.uql.app/transactions-declarative)**  | Standard `@Transactional()` and `@InjectQuerier()` decorators for NestJS/DI.                                                |
 | **[Modern & Versatile](https://uql.app/entities/virtual-fields)** | **Pure ESM**, high-res timing, [Soft-delete](https://uql.app/entities/soft-delete), and **Vector/JSONB/JSON** support. |
-| **Structured Logging**                                             | Professional-grade monitoring with slow-query detection and colored output.                                                     |
+| **[Database Migrations](https://www.uql.app/migrations)**          | Built-in [Entity-First synchronization](https://uql.app/migrations#3-entity-first-synchronization-development) and a robust CLI for version-controlled schema evolution. |
+| **[Logging & Monitoring](https://www.uql.app/logging)**               | Professional-grade monitoring with slow-query detection and colored output.                                                     |
 
  
 
@@ -364,13 +365,14 @@ export default {
 
 ### 2. Manage via CLI
 
-
 Use the CLI to manage your database schema evolution.
 
 | Command | Description |
 | :--- | :--- |
 | `generate <name>` | Creates an empty timestamped file for **manual** SQL migrations (e.g., data backfills). |
 | `generate:entities <name>` | **Auto-generates** a migration by diffing your entities against the current DB schema. |
+| `generate:from-db` | **Scaffolds Entities** from an existing database. Includes **Smart Relation Detection**. |
+| `drift:check` | **Drift Detection**: Compares your defined entities against the actual database schema and reports discrepancies. |
 | `up` | Applies all pending migrations. |
 | `down` | Rolls back the last applied migration batch. |
 | `status` | Shows which migrations have been executed and which are pending. |
@@ -387,11 +389,11 @@ npx uql-migrate generate:entities add_profile_table
 # 3. Apply changes
 npx uql-migrate up
 
-# 4. Revert changes if needed
-npx uql-migrate down
+# 4. Check for schema drift (Production Safety)
+npx uql-migrate drift:check
 
-# 5. Run with custom config
-npx uql-migrate up --config ./configs/uql.config.ts
+# 5. Scaffold entities from an existing DB (Legacy Adoption)
+npx uql-migrate generate:from-db --output ./src/entities
 ```
 
 > **Bun Users**: If your `uql.config.ts` uses TypeScript path aliases (e.g., `~app/...`), run migrations with the `--bun` flag to ensure proper resolution:
@@ -404,6 +406,12 @@ npx uql-migrate up --config ./configs/uql.config.ts
 
 Keep your schema in sync without manual migrations. It is **Safe by Default**: In safe mode (default), it strictly **adds** new tables and columns but **blocks** any destructive operations (column drops or type alterations) to prevent data loss. It provides **Transparent Feedback** by logging detailed warnings for any blocked changes, so you know exactly what remains to be migrated manually.
 
+**New Capabilities (v3.8+):**
+
+*   **Schema AST Engine**: Uses a graph-based representation of your schema for 100% accurate diffing, handling circular dependencies and correct topological sort orders for table creation/dropping.
+*   **Smart Relation Detection**: When generating entities from an existing DB, UQL automatically detects relationships (OneToOne, ManyToMany) via foreign key structures and naming conventions (`user_id` -> `User`).
+*   **Bidirectional Index Sync**: Indexes defined in `@Field({ index: true })` or `@Index()` are synced to the DB, and indexes found in the DB are reflected in generated entities.
+
 > **Important**: For `autoSync` to detect your entities, they must be **loaded** (imported) before calling `autoSync`.
 
 **Using Your Config (Recommended)**

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

@@ -32,11 +32,11 @@ var _dec, _dec1, _dec2, _dec3, _dec4, _dec5, _dec6, /**
    * `onDelete` callback allows to specify which field will be used when deleting/querying this entity.
    */ _init_deletedAt, _dec42, _initClass8, _BaseEntity7, _dec43, _dec44, _dec45, _dec46, _init_name7, _init_categoryId1, _init_category1, _init_deletedAt1, _dec47, _initClass9, _BaseEntity8, _dec48, _dec49, _dec50, _init_name8, _init_address, _init_description4, _dec51, _initClass10, _BaseEntity9, _dec52, _dec53, _dec54, _dec55, _dec56, _dec57, _dec58, _dec59, _dec60, _dec61, _dec62, _dec63, _dec64, _dec65, _dec66, _init_name9, _init_description5, _init_code, _init_buyLedgerAccountId, _init_buyLedgerAccount, _init_saleLedgerAccountId, _init_saleLedgerAccount, _init_taxId, _init_tax, _init_measureUnitId, _init_measureUnit, _init_salePrice, _init_inventoryable, _init_tags, _init_tagsCount, _dec67, _initClass11, _BaseEntity10, _dec68, _dec69, _dec70, _init_name10, _init_items, _init_itemsCount, _dec71, _initClass12, _dec72, _dec73, _dec74, _init_id2, _init_itemId, _init_tagId, _dec75, _initClass13, _BaseEntity11, _dec76, _dec77, _dec78, _init_itemAdjustments, _init_date, _init_description6, _dec79, _initClass14, _BaseEntity12, _dec80, _dec81, _dec82, _dec83, _dec84, _dec85, _dec86, _dec87, _init_itemId1, _init_item, _init_number, _init_buyPrice, _init_storehouseId, _init_storehouse, _init_inventoryAdjustmentId, _init_inventoryAdjustment;
 _dec = Id(), _dec1 = Field({
-    reference: ()=>_Company
+    references: ()=>_Company
 }), _dec2 = ManyToOne({
     entity: ()=>_Company
 }), _dec3 = Field({
-    reference: ()=>_User
+    references: ()=>_User
 }), _dec4 = ManyToOne({
     entity: ()=>_User
 }), _dec5 = Field({
@@ -243,7 +243,7 @@ class UserWithNonUpdatableId {
 }
 let _LedgerAccount;
 _dec23 = Entity(), _dec24 = Field(), _dec25 = Field(), _dec26 = Field({
-    reference: ()=>_LedgerAccount
+    references: ()=>_LedgerAccount
 }), _dec27 = ManyToOne();
 class LedgerAccount extends (_BaseEntity3 = BaseEntity) {
     static{
@@ -314,7 +314,7 @@ class TaxCategory extends (_BaseEntity4 = BaseEntity) {
 }
 let _Tax;
 _dec32 = Entity(), _dec33 = Field(), _dec34 = Field(), _dec35 = Field({
-    reference: ()=>_TaxCategory
+    references: ()=>_TaxCategory
 }), _dec36 = ManyToOne(), _dec37 = Field();
 class Tax extends (_BaseEntity5 = BaseEntity) {
     static{
@@ -397,7 +397,7 @@ let _MeasureUnit;
 _dec42 = Entity({
     softDelete: true
 }), _dec43 = Field(), _dec44 = Field({
-    reference: ()=>_MeasureUnitCategory
+    references: ()=>_MeasureUnitCategory
 }), _dec45 = ManyToOne({
     cascade: 'persist'
 }), _dec46 = Field({
@@ -470,13 +470,13 @@ class Storehouse extends (_BaseEntity8 = BaseEntity) {
 }
 let _Item;
 _dec51 = Entity(), _dec52 = Field(), _dec53 = Field(), _dec54 = Field(), _dec55 = Field({
-    reference: ()=>_LedgerAccount
+    references: ()=>_LedgerAccount
 }), _dec56 = ManyToOne(), _dec57 = Field({
-    reference: ()=>_LedgerAccount
+    references: ()=>_LedgerAccount
 }), _dec58 = ManyToOne(), _dec59 = Field({
-    reference: ()=>_Tax
+    references: ()=>_Tax
 }), _dec60 = ManyToOne(), _dec61 = Field({
-    reference: ()=>_MeasureUnit
+    references: ()=>_MeasureUnit
 }), _dec62 = ManyToOne(), _dec63 = Field(), _dec64 = Field(), _dec65 = ManyToMany({
     entity: ()=>_Tag,
     through: ()=>_ItemTag,
@@ -640,9 +640,9 @@ class Tag extends (_BaseEntity10 = BaseEntity) {
 }
 let _ItemTag;
 _dec71 = Entity(), _dec72 = Id(), _dec73 = Field({
-    reference: ()=>_Item
+    references: ()=>_Item
 }), _dec74 = Field({
-    reference: ()=>_Tag
+    references: ()=>_Tag
 });
 class ItemTag {
     static{
@@ -712,11 +712,11 @@ class InventoryAdjustment extends (_BaseEntity11 = BaseEntity) {
 }
 let _ItemAdjustment;
 _dec79 = Entity(), _dec80 = Field({
-    reference: ()=>_Item
+    references: ()=>_Item
 }), _dec81 = ManyToOne(), _dec82 = Field(), _dec83 = Field(), _dec84 = Field({
-    reference: ()=>_Storehouse
+    references: ()=>_Storehouse
 }), _dec85 = ManyToOne(), _dec86 = Field({
-    reference: ()=>_InventoryAdjustment
+    references: ()=>_InventoryAdjustment
 }), _dec87 = ManyToOne();
 class ItemAdjustment extends (_BaseEntity12 = BaseEntity) {
     static{
@@ -879,7 +879,8 @@ function fillInverseSideRelations(relOpts) {
 function fillThroughRelations(entity) {
     const meta = ensureMeta(entity);
     meta.relations = getKeys(meta.fields).reduce((relations, key)=>{
-        const { reference } = meta.fields[key];
+        const field = meta.fields[key];
+        const reference = field.references ?? field.reference;
         if (reference) {
             const relEntity = reference();
             const relMeta = ensureMeta(relEntity);