uql-orm 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file. Please add
 
 date format is [yyyy-mm-dd]
 
+## [0.6.0] - 2026-03-18
+### Features
+- **JSON update operators expanded**: Added `$push` for atomic JSON array append in update payloads across SQL dialects.
+- **Unified JSON update API type**: Introduced `JsonUpdateOp` with type-safe `$merge`, `$unset`, and `$push` support for `Json<T>` fields.
+
+### Bug Fixes
+- **MariaDB JSON dot-notation correctness**: Fixed JSON path extraction for MariaDB by using `JSON_VALUE(...)` instead of MySQL-style `->` / `->>` operators.
+- **PostgreSQL operator chaining semantics**: Fixed `$merge + $push` evaluation when targeting the same key so `$push` reads from the current intermediate expression (not stale column state).
+
+### Testing
+- Added multi-dialect regression tests for JSON update chaining (`$merge`, `$push`, `$unset`), including same-key `$merge + $push` behavior.
+- Added MariaDB-specific regression tests for dot-notation filtering/sorting SQL generation (`JSON_VALUE` paths).
+
+## [0.5.2] - 2026-03-17
+### Testing
+- **Suite reliability**: Ensured the full test suite runs without runtime errors across all dialects with coverage thresholds still met (>97% statements, >90% branches).
+
 ## [0.5.1] - 2026-03-15
 ### Chore
 - **Documentation**: Unified documentation strategy using NPM lifecycle scripts across subpackages.

package/README.md

@@ -4,7 +4,7 @@
 
 [![tests](https://github.com/rogerpadilla/uql/actions/workflows/tests.yml/badge.svg)](https://github.com/rogerpadilla/uql) [![Coverage Status](https://coveralls.io/repos/github/rogerpadilla/uql/badge.svg?branch=main)](https://coveralls.io/github/rogerpadilla/uql?branch=main) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/rogerpadilla/uql/blob/main/LICENSE) [![npm version](https://img.shields.io/npm/v/uql-orm.svg)](https://www.npmjs.com/package/uql-orm)
 
-**[UQL](https://uql-orm.dev)** is a clean, ultra-fast TypeScript ORM designed for developers who value portability and performance. It eliminates the friction between SQL and MongoDB, providing a unified, type-safe experience without proprietary DSLs or heavy codegen steps.
+**[UQL](https://uql-orm.dev)** is a TypeScript ORM focused on portability, performance, and a consistent query model across SQL and MongoDB. In our open benchmark, SQL generation reaches [**3.9M+ ops/s**](https://github.com/rogerpadilla/ts-orm-benchmark). UQL is designed for teams that want type safety and dialect portability without introducing a proprietary query DSL.
 
 ```ts
 const results = await querier.findMany(User, {
@@ -15,28 +15,61 @@ const results = await querier.findMany(User, {
 });
 ```
 
- 
+## Quick Start
+
+```sh
+npm install uql-orm pg
+```
+
+```ts
+import { PgQuerierPool } from 'uql-orm/postgres';
+
+const pool = new PgQuerierPool({ host: 'localhost', database: 'app' });
+const users = await pool.withQuerier((querier) => querier.findMany(User, { $limit: 10 }));
+```
+
+For production setup and migrations, jump to:
+- [Install](#1-install)
+- [Define your Entities](#2-define-your-entities)
+- [Migrations & Synchronization](#5-migrations--synchronization)
+
+> **Note:** For explicit lifecycle control, use manual `getQuerier()` + `release()` (shown in [Core Query Pattern](#core-query-pattern)).
+
+## Guide Map
+
+Core path:
+- [1. Install](#1-install)
+- [2. Define your Entities](#2-define-your-entities)
+- [3. Set up a pool](#3-set-up-a-pool)
+- [4. Manipulate the Data](#4-manipulate-the-data)
+- [5. Migrations & Synchronization](#5-migrations--synchronization)
+
+Advanced and operations:
+- [Semantic Search](#modern-indexing-semantic-search)
+- [JSON Operators & Relation Filtering](#json-operators--relation-filtering)
+- [Thread-Safe Transactions](#thread-safe-transactions)
+- [6. Logging & Monitoring](#6-logging--monitoring)
+- [Deep Dive: Tests & Technical Resources](#deep-dive-tests--technical-resources)
 
 ## Features
 
 | Feature | Why it matters |
 | :--- | :--- |
 | **[Intelligent Querying](https://uql-orm.dev/querying/relations)** | Deep auto-completion for operators and relations at any depth—no more guessing property names. |
-| **Serializable JSON** | 100% valid JSON queries. Send your query logic over HTTP or WebSockets as easily as a string. |
-| **Unified Dialects** | Write once, run anywhere. Seamlessly switch between PostgreSQL, MySQL, SQLite, and MongoDB. |
+| **Serializable JSON** | Query objects are valid JSON, which makes them straightforward to transport over HTTP/gRPC/WebSockets. |
+| **Unified Dialects** | Write once, run anywhere. Seamlessly switch between PostgreSQL, MySQL, MariaDB, SQLite, and MongoDB. |
 | **[Naming Strategies](https://uql-orm.dev/naming-strategy)** | No more `camelCase` vs `snake_case` headaches. Map your code to your database automatically. |
-| **Smart SQL Engine** | Zero-allocation SQL generation. Built for high-throughput apps where every millisecond counts. |
+| **Smart SQL Engine** | Zero-allocation SQL generation with top-ranked results in our [open benchmark](https://github.com/rogerpadilla/ts-orm-benchmark). |
 | **Thread-Safe by Design** | Protect your data integrity with centralized task queues and the `@Serialized()` decorator. |
 | **[Declarative Transactions](https://uql-orm.dev/querying/transactions)** | Clean `@Transactional()` decorators that work beautifully with modern DI frameworks like NestJS. |
 | **[Lifecycle Hooks](https://uql-orm.dev/entities/lifecycle-hooks)** | Automate validation, timestamps, and computed logic with intuitive class-based decorators. |
 | **[Aggregate Queries](https://uql-orm.dev/querying/aggregate)** | Real-time analytics with `GROUP BY`, `HAVING`, and native math operators across all dialects. |
 | **[Semantic Search](https://uql-orm.dev/querying/semantic-search)** | Native vector similarity search. Rank results by meaning using standard ORM operators. |
 | **[Cursor Streaming](https://uql-orm.dev/querying/streaming)** | Process millions of rows with a stable memory footprint using native driver-level cursors. |
-| **[Modern & Versatile](https://uql-orm.dev/entities/virtual-fields)** | Pure ESM, high-res timing, built-in soft-delete, and first-class JSONB/JSON support. |
+| **[Modern & Versatile](https://uql-orm.dev/entities/virtual-fields)** | Pure ESM, high-res timing, built-in soft-delete, and first-class JSON/JSONB support. |
 | **[Database Migrations](https://www.uql-orm.dev/migrations)** | Entity-First synchronization. DDL is auto-generated by diffing your code against the live DB. |
 | **[Logging & Monitoring](https://www.uql-orm.dev/logging)** | High-visibility debugging with slow-query detection and high-contrast terminal output. |
-
- 
+| **[Fullstack Bridge](https://www.uql-orm.dev/comparison#network-boundaries--apis)** | Speak to your database from the browser securely. First-party `HttpQuerier` removes API boilerplate. |
 
 ## 1. Install
 
@@ -57,7 +90,6 @@ npm install uql-orm       # or bun add / pnpm add
 | **SQLite** | `npm install better-sqlite3` |
 | **LibSQL** (incl. Turso) | `npm install @libsql/client` |
 | **MongoDB** | `npm install mongodb` |
-| **CockroachDB** | `npm install pg` |
 | **Cloudflare D1** | _Native (no driver needed)_ |
 
 ### TypeScript Configuration
@@ -73,7 +105,7 @@ Ensure your `tsconfig.json` is configured to support decorators and metadata:
 }
 ```
 
- **Note:** UQL is Modern Pure ESM — ensure your project's `module` supports ESM imports (e.g., `NodeNext`, `ESNext`, `Bundler`).
+> **Note:** UQL is Modern Pure ESM — ensure your project's `module` supports ESM imports (e.g., `NodeNext`, `ESNext`, `Bundler`).
 
 ## 2. Define your Entities
 
@@ -129,9 +161,6 @@ price?: number;
 statusCode?: number;
 ```
 
-
- 
-
 ```ts
 import { v7 as uuidv7 } from 'uuid';
 import { Entity, Id, Field, OneToOne, OneToMany, ManyToOne, ManyToMany, type Relation, type Json } from 'uql-orm';
@@ -224,9 +253,7 @@ export class PostTag {
 }
 ```
 
-> **Senior Insight**: Use the `Relation<T>` utility type for relationship properties. It prevents TypeScript circular dependency errors while maintaining full type-safety throughout your app.
-
-&nbsp;
+> **Note:** Use the `Relation<T>` utility type for relationship properties. It prevents TypeScript circular dependency errors while maintaining full type-safety throughout your app.
 
 ## 3. Set up a pool
 
@@ -241,7 +268,7 @@ export const pool = new PgQuerierPool(
   { host: 'localhost', database: 'uql_app', max: 10 },
   {
     logger: ['error', 'warn', 'migration'],
-    namingStrategy: new SnakeCaseNamingStrategy()
+    namingStrategy: new SnakeCaseNamingStrategy(),
     slowQuery: { threshold: 1000 },
   }
 );
@@ -253,27 +280,27 @@ export default {
 } satisfies Config;
 ```
 
-> **Senior Insight**: Don't overcomplicate your setup. Reusing the same connection pool for both your application and migrations reduces overhead and ensures consistent behavior (like naming strategies) across your entire stack.
-
-&nbsp;
-
-&nbsp;
+> **Notes:**
+> - Reuse one pool for both app queries and migrations to keep behavior (for example naming strategy) consistent.
+> - If your architecture spans backend + browser, `HttpQuerier` reduces custom API mapping and keeps query semantics aligned.
 
 ## 4. Manipulate the Data
 
 UQL provides a straightforward API to interact with your data. **Always ensure queriers are released back to the pool.**
 
+### Core Query Pattern
+
 ```ts
 const querier = await pool.getQuerier();
 try {
   const results = await querier.findMany(User, {
     $select: {
       name: true,
-      profile: { $select: { bio: true }, $required: true } // INNER JOIN
+      profile: { $select: { bio: true }, $required: true }, // INNER JOIN
     },
     $where: {
       status: 'active',
-      name: { $istartsWith: 'a' }
+      name: { $istartsWith: 'a' },
     },
     $limit: 10,
   });
@@ -292,7 +319,19 @@ WHERE "User"."status" = 'active' AND "User"."name" ILIKE 'a%'
 LIMIT 10 OFFSET 0
 ```
 
-&nbsp;
+### Advanced Query Patterns
+
+### Modern Indexing: Semantic Search
+
+AI-driven applications require ranking results by meaning. UQL treats vector similarity as a first-class citizen, allowing you to perform semantic search without raw SQL or proprietary extensions.
+
+```ts
+const results = await querier.findMany(Item, {
+  $select: { id: true, title: true },
+  $sort: { $vector: { embedding: queryVector } },
+  $limit: 10,
+});
+```
 
 ### Advanced: Virtual Fields & Raw SQL
 
@@ -314,11 +353,9 @@ export class Item {
 }
 ```
 
-&nbsp;
+### JSON Operators & Relation Filtering
 
-### JSONB Operators & Relation Filtering
-
-Query nested JSON fields using **type-safe dot-notation** with full operator support. Wrap fields with `Json<T>` to get IDE autocompletion for valid paths. UQL generates the correct SQL for each dialect.
+Query nested JSON fields using **type-safe dot-notation** with full operator support. Wrap fields with `Json<T>` to get IDE autocompletion for valid paths. UQL generates native SQL per dialect.
 
 ```ts
 // Filter by nested JSONB field paths
@@ -330,9 +367,22 @@ const items = await querier.findMany(Company, {
 });
 ```
 
-**PostgreSQL:** `WHERE ("settings"->>'isArchived') IS DISTINCT FROM $1 AND (("settings"->>'priority'))::numeric >= $2`
+**PostgreSQL:** `WHERE ("settings"->>'isArchived') IS DISTINCT FROM $1 AND (("settings"->>'priority'))::numeric >= $2`  
+**MySQL:** `WHERE (\`settings\`->>'isArchived') <> ? AND CAST((\`settings\`->>'priority') AS DECIMAL) >= ?`  
+**MariaDB:** `WHERE JSON_VALUE(\`settings\`, '$.isArchived') <> ? AND CAST(JSON_VALUE(\`settings\`, '$.priority') AS DECIMAL) >= ?`  
 **SQLite:** `WHERE json_extract("settings", '$.isArchived') IS NOT ? AND CAST(json_extract("settings", '$.priority') AS REAL) >= ?`
 
+Atomic JSON updates support `$merge`, `$unset`, and `$push`:
+
+```ts
+await querier.updateOneById(Company, id, {
+  settings: { $merge: { theme: 'dark' }, $push: { tags: 'orm' }, $unset: ['deprecated'] },
+});
+```
+
+> **Modern DB Baselines used by docs/examples:** PostgreSQL 16+, MySQL 8.4+ (LTS), MariaDB 12.2+, SQLite 3.45+.
+> Full generated SQL examples: [JSON / JSONB docs](https://uql-orm.dev/querying/json).
+
 Filter parent entities by their **ManyToMany** or **OneToMany** relations using automatic EXISTS subqueries:
 
 ```ts
@@ -344,9 +394,7 @@ const posts = await querier.findMany(Post, {
 
 **PostgreSQL:** `WHERE EXISTS (SELECT 1 FROM "PostTag" WHERE "PostTag"."postId" = "Post"."id" AND "PostTag"."tagId" IN (SELECT "Tag"."id" FROM "Tag" WHERE "Tag"."name" = $1))`
 
-> **Senior Insight**: Wrap your JSON fields with `Json<T>` to get deep autocompletion for dot-notation paths. It turns a "guess and check" process into a type-safe workflow.
-
-&nbsp;
+> **Note:** Wrap JSON fields with `Json<T>` to get autocompletion for valid dot-notation paths.
 
 ### Aggregate Queries
 
@@ -388,8 +436,6 @@ const names = await querier.findMany(User, {
 
 > **Learn more**: See the full [Aggregate Queries guide](https://uql-orm.dev/querying/aggregate) for `$having` operators, MongoDB pipeline details, and advanced patterns.
 
-&nbsp;
-
 ### Cursor-Based Streaming
 
 For large result sets, use `findManyStream()` to iterate row-by-row without loading everything into memory. Each driver uses its optimal native cursor API.
@@ -400,8 +446,6 @@ for await (const user of querier.findManyStream(User, { $where: { active: true }
 }
 ```
 
-&nbsp;
-
 ### Thread-Safe Transactions
 
 UQL is one of the few ORMs with a **centralized serialization engine**. Transactions are guaranteed to be race-condition free.
@@ -452,8 +496,6 @@ try {
 }
 ```
 
-&nbsp;
-
 ## 5. Migrations & Synchronization
 
 UQL takes an **Entity-First** approach. You modify your TypeScript classes, and UQL handles the heavy lifting—auto-generating migration files by diffing your code against the live database.
@@ -467,7 +509,7 @@ npx uql-migrate generate:entities add_user_nickname
 npx uql-migrate up
 ```
 
-> **Senior Insight**: Your entities are the single source of truth. This workflow eliminates the "drift" between what's in your code and what's in production.
+> **Note:** Keep entities as the source of truth to minimize drift between code and database schema.
 
 ### 1. Unified Configuration
 
@@ -527,7 +569,7 @@ npx uql-migrate generate seed_default_roles
 
 ### 3. AutoSync (Development)
 
-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.
+Keep your schema in sync without manual migrations. It is **safe by default**: in safe mode (default), it adds new tables/columns and blocks destructive changes (column drops or type alterations). Blocked actions are logged so you can migrate them manually.
 
 **New Capabilities (v3.8+):**
 
@@ -565,11 +607,13 @@ const migrator = new Migrator(pool, {
 await migrator.autoSync({ logging: true });
 ```
 
-&nbsp;
+> **Note:** In development, `autoSync` accelerates iteration while still protecting data by blocking destructive schema changes.
+
+## Operations
 
-## 6. Logging & Monitoring
+### 6. Logging & Monitoring
 
-UQL features a professional-grade, structured logging system designed for high visibility and sub-millisecond performance monitoring.
+UQL includes a structured logging system for query visibility and performance monitoring.
 
 ### Log Levels
 
@@ -584,7 +628,7 @@ UQL features a professional-grade, structured logging system designed for high v
 
 ### Visual Feedback
 
-The `DefaultLogger` provides high-contrast, colored output that makes debugging feel like a premium experience:
+The `DefaultLogger` provides high-contrast, colored output for quick debugging:
 
 ```text
 query: SELECT * FROM "user" WHERE "id" = $1 -- [123] [2ms]
@@ -592,9 +636,7 @@ slow query: UPDATE "post" SET "title" = $1 -- ["New Title"] [1250ms]
 error: Failed to connect to database: Connection timeout
 ```
 
-> **Senior Insight**: In production, keep your logs lean. By setting `logger: ['error', 'warn', 'slowQuery']`, UQL stays silent until a performance bottleneck actually occurs.
-
-&nbsp;
+> **Note:** In production, keep logs lean with `logger: ['error', 'warn', 'slowQuery']`.
 
 Learn more about UQL at [uql-orm.dev](https://uql-orm.dev) for details on:
 
@@ -606,9 +648,7 @@ Learn more about UQL at [uql-orm.dev](https://uql-orm.dev) for details on:
 - [Soft Deletes &amp; Auditing](https://uql-orm.dev/entities/soft-delete)
 - [Database Migration &amp; Syncing](https://uql-orm.dev/migrations)
 
-&nbsp;
-
-## 🛠 Deep Dive: Tests & Technical Resources
+### Deep Dive: Tests & Technical Resources
 
 For those who want to see the "engine under the hood," check out these resources in the source code:
 
@@ -619,8 +659,6 @@ For those who want to see the "engine under the hood," check out these resources
   - [PostgreSQL](https://github.com/rogerpadilla/uql/blob/main/packages/uql-orm/src/postgres/postgresDialect.spec.ts) \| [MySQL](https://github.com/rogerpadilla/uql/blob/main/packages/uql-orm/src/mysql/mysqlDialect.spec.ts) \| [SQLite](https://github.com/rogerpadilla/uql/blob/main/packages/uql-orm/src/sqlite/sqliteDialect.spec.ts) specs.
   - [Querier Integration Tests](https://github.com/rogerpadilla/uql/blob/main/packages/uql-orm/src/querier/abstractSqlQuerier-spec.ts): SQL generation & connection management tests.
 
-&nbsp;
-
 ## Built with ❤️ and supported by
 
 UQL is an open-source project proudly sponsored by **[Variability.ai](https://variability.ai)**.