@uql/core 3.11.1 → 3.12.0

package/CHANGELOG.md

@@ -3,9 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [3.11.1](https://github.com/rogerpadilla/uql/compare/@uql/core@3.11.0...@uql/core@3.11.1) (2026-02-26)
+# [3.12.0](https://github.com/rogerpadilla/uql/compare/@uql/core@3.11.1...@uql/core@3.12.0) (2026-03-05)
 
-**Note:** Version bump only for package @uql/core
+
+### Features
+
+* introduce JSONB dot-notation filtering in `where` clauses and fix `raw()` expression prefixing in logical operators. ([669257d](https://github.com/rogerpadilla/uql/commit/669257d497e08729094a9f178685ca6665b8b20b))
 
 
 
@@ -17,6 +20,40 @@ All notable changes to this project will be documented in this file. Please add
 
 date format is [yyyy-mm-dd]
 
+## [3.12.0] - 2026-03-05
+### New Features
+- **JSONB Dot-Notation Operators**: Filter by nested JSON field paths directly in `$where` with full operator support (`$eq`, `$ne`, `$gt`, `$lt`, `$like`, `$ilike`, `$in`, `$nin`, `$regex`, etc.). Works across PostgreSQL, MySQL, and SQLite.
+  ```ts
+  await querier.findMany(User, {
+    $where: { 'settings.isArchived': { $ne: true } },
+  });
+  ```
+- **Relation Filtering**: Filter by ManyToMany and OneToMany relations using automatic EXISTS subqueries. No more manual `raw()` joins.
+  ```ts
+  await querier.findMany(Item, {
+    $where: { tags: { name: 'important' } },
+  });
+  ```
+- **`Json<T>` Marker Type**: Wrap JSONB field types with `Json<T>` to ensure they are classified as `FieldKey` (not `RelationKey`), enabling type-safe usage in `$where`, `$select`, and `$sort`.
+  ```ts
+  @Field({ type: 'jsonb' })
+  settings?: Json<{ isArchived?: boolean }>;
+  ```
+- **`JsonFieldPaths<E>` Autocompletion**: Template literal type that derives valid dot-notation paths from `Json<T>` fields (e.g., `'kind.public' | 'kind.private'`). Provides IDE autocompletion for JSONB `$where` queries without restricting arbitrary string paths.
+
+### Bug Fixes
+- **raw() String Prefix Fix**: String-based `raw()` values in `$and`/`$or` are no longer incorrectly table-prefixed (e.g., `raw("kind IS NOT NULL")` previously produced `resource.kind IS NOT NULL` instead of `kind IS NOT NULL`).
+
+### Improvements & Refactoring
+- **DRY JSON Config**: Extracted `getBaseJsonConfig()` in each dialect — `$elemMatch` and dot-notation now compose from a single config source, eliminating ~20 lines of duplication.
+- **Extracted `normalizeWhereValue()`**: Deduplicated the `Array→$in / object→passthrough / scalar→$eq` normalization used by both regular field and JSON path comparisons.
+- **Cleaner Dot-Notation Detection**: Uses `indexOf`+`slice` instead of two `split('.')` calls for efficient dot-path parsing.
+- **Relation Safety Guard**: `compareRelation()` now throws a descriptive `TypeError` if `rel.references` is missing, instead of a cryptic undefined crash.
+- **TypeScript 6 Compatibility**: Fixed `QueryWhereMap` circular type reference and expanded `QueryWhereOptions.clause` union.
+
+### Test Coverage
+- **46 new tests** across 3 dialects (base, PostgreSQL, SQLite) covering all new features and edge cases. Total: **1561 tests passing**.
+
 ## [3.11.1] - 2026-02-26
 ### Improvements
 - **Expanded ColumnType Aliases**: Added `integer`, `tinyint`, `bool`, `datetime`, and `smallserial` as first-class `ColumnType` values (aliases for `int`, `boolean`, `timestamp`, `smallserial`, and `serial` respectively). Users can now use standard SQL keywords interchangeably (e.g., `integer` or `int`, `bool` or `boolean`, `datetime` or `timestamp`).

package/README.md

@@ -112,7 +112,7 @@ UQL separates the **intent** of your data from its **storage**. Both properties
 externalId?: string;
 
 @Field({ type: 'json' })          // → JSONB (Postgres), JSON (MySQL), TEXT (SQLite)
-metadata?: Record<string, unknown>;
+metadata?: Json<{ theme?: string }>;
 
 // Logical types with constraints - portable with control
 @Field({ type: 'varchar', length: 500 })
@@ -131,7 +131,7 @@ statusCode?: number;
 
 ```ts
 import { v7 as uuidv7 } from 'uuid';
-import { Entity, Id, Field, OneToOne, OneToMany, ManyToOne, ManyToMany, type Relation } from '@uql/core';
+import { Entity, Id, Field, OneToOne, OneToMany, ManyToOne, ManyToMany, type Relation, type Json } from '@uql/core';
 
 @Entity()
 export class User {
@@ -314,6 +314,38 @@ export class Item {
 
 &nbsp;
 
+### 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.
+
+```ts
+// Filter by nested JSONB field paths
+const items = await querier.findMany(Company, {
+  $where: {
+    'settings.isArchived': { $ne: true },
+    'settings.priority': { $gte: 5 },
+  },
+});
+```
+
+**PostgreSQL:** `WHERE ("settings"->>'isArchived') <> $1 AND (("settings"->>'priority'))::numeric >= $2`
+**SQLite:** `WHERE json_extract("settings", '$.isArchived') <> ? AND CAST(json_extract("settings", '$.priority') AS REAL) >= ?`
+
+Filter parent entities by their **ManyToMany** or **OneToMany** relations using automatic EXISTS subqueries:
+
+```ts
+// Find posts that have a tag named 'typescript'
+const posts = await querier.findMany(Post, {
+  $where: { tags: { name: 'typescript' } },
+});
+```
+
+**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))`
+
+> **Pro Tip**: Wrap JSONB field types with `Json<T>` (e.g., `settings?: Json<{ isArchived?: boolean }>`) to get IDE autocompletion for dot-notation paths.
+
+&nbsp;
+
 ### Thread-Safe Transactions
 
 UQL is one of the few ORMs with a **centralized serialization engine**. Transactions are guaranteed to be race-condition free.