@uql/core 3.11.1 → 3.12.1

package/CHANGELOG.md

@@ -3,9 +3,17 @@
 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.1](https://github.com/rogerpadilla/uql/compare/@uql/core@3.12.0...@uql/core@3.12.1) (2026-03-05)
 
-**Note:** Version bump only for package @uql/core
+
+### Bug Fixes
+
+* Make JSONB `$ne` operator null-safe by using `IS DISTINCT FROM` / `IS NOT` and refine query map type definitions. ([2bb2023](https://github.com/rogerpadilla/uql/commit/2bb202310d5a1a7fa2bc0ff7948c892afa4ba4f2))
+
+
+### Features
+
+* Enhance `QueryWhereMap` type for improved JSONB dot-notation and relation filtering, eliminating `as any` casts in tests. ([2092e11](https://github.com/rogerpadilla/uql/commit/2092e113d858130941a0d0b2807026b73c852946))
 
 
 
@@ -17,6 +25,54 @@ All notable changes to this project will be documented in this file. Please add
 
 date format is [yyyy-mm-dd]
 
+## [3.12.1] - 2026-03-05
+### Bug Fixes
+- **Null-Safe JSONB `$ne`**: JSONB dot-notation `$ne` now uses null-safe operators (`IS DISTINCT FROM` on PostgreSQL, `IS NOT` on SQLite) so that absent keys (which return SQL `NULL`) are correctly included in results. Previously, `{ 'settings.isArchived': { $ne: true } }` would silently exclude rows where the key didn't exist.
+- **JSONB `$eq`/`$ne` with `null`**: `$eq: null` and `$ne: null` on JSONB paths now correctly generate `IS NULL` / `IS NOT NULL` instead of `= NULL` / `<> NULL`.
+
+### Improvements & Refactoring
+- **`QueryWhereMap` Type Safety**: Replaced the overly permissive `Record<string, ...>` catch-all with explicit typed unions: template literal `` `${string}.${string}` `` for dot-paths, `RelationKey<E>` for relation filtering, and `JsonFieldPaths<E>` for IDE autocompletion.
+- **`DeepJsonKeys` Recursive Type**: `JsonFieldPaths<E>` now derives dot-notation paths up to 5 levels deep (previously only 1 level), enabling autocompletion for nested JSONB structures like `'kind.theme.color'`.
+- **DRY `compare()` Signature**: Simplified `compare()` from `<E, K extends keyof QueryWhereMap<E>>(key: K, val: QueryWhereMap<E>[K])` to `<E>(key: string, val: unknown)` across all dialect overrides, removing redundant generic constraints.
+- **DRY SQLite Config**: SQLite's `getBaseJsonConfig()` now spreads from `super` instead of duplicating 4 identical fields.
+
+### Test Coverage
+- Removed ~20 `as any` casts from tests (now unnecessary with improved types). Added null-safe `$ne` tests across all dialects. Total: **1,563 tests passing**.
+
+## [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') IS DISTINCT FROM $1 AND (("settings"->>'priority'))::numeric >= $2`
+**SQLite:** `WHERE json_extract("settings", '$.isArchived') IS NOT ? 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.