uql-orm 0.9.3 → 0.9.5

package/README.md

@@ -1,749 +1,128 @@
 <!-- ![code](/assets/code.webp 'code') -->
 
-<a href="https://uql-orm.dev"><img src="assets/logo.svg" alt="uql" width="80" /></a>
+<picture>
+  <source srcset="assets/logo-dark.svg" media="(prefers-color-scheme: dark)">
+  <a href="https://uql-orm.dev"><img src="assets/logo.svg" alt="uql" width="80" /></a>
+</picture>
 
-[![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)
+[![tests](https://github.com/rogerpadilla/uql/actions/workflows/tests.yml/badge.svg)](https://github.com/rogerpadilla/uql/actions/workflows/tests.yml) [![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 the best ORM for TypeScript and modern JavaScript designed to be fast, safe, and easy to integrate into any application — especially AI and data‑heavy workloads. Built with a unified API across SQL and MongoDB.
+**[UQL](https://uql-orm.dev)** is the JSON-native TypeScript ORM: serializable queries, no codegen, and one API across PostgreSQL, MySQL, SQLite, MariaDB, and MongoDB. Define entities once, query everywhere.
+
+<!-- DEMO: Record an animated GIF showing IDE autocompletion for $select/$populate/$where and embed here. Example: ![demo](/assets/demo.gif) -->
 
 ```ts
-const results = await querier.findMany(User, {
-  $select: { name: true },
-  $populate: { profile: { $select: { picture: true } } },
-  $where: { name: { $istartsWith: 'a' }, posts: { tags: { name: 'typescript' } } },
-  $sort: { createdAt: 'desc' },
+await querier.findMany(User, {
+  $select: { id: true, name: true },
+  $where: { email: { $endsWith: '@uql-orm.dev' } },
   $limit: 10,
 });
 ```
 
-## Quick Start
-
-```sh
-npm install uql-orm pg
-```
-_(Example using PostgreSQL; see [Install](#1-install) for other databases)_
-
-```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)
+Full docs: **[uql-orm.dev](https://uql-orm.dev)**
 
-> **Note:** For explicit lifecycle control, use manual `getQuerier()` + `release()` (shown in [Core Query Pattern](#core-query-pattern)).
+---
 
-## Guide Map
+## Why UQL?
 
-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)
+- **Queries are data, not method chains.** A UQL query is a plain JSON object. Build them dynamically, store them, or send them from client to server without a DSL.
+- **No codegen, no build step.** Entities are TypeScript classes, so your code *is* the schema. No `.prisma` files or generated clients to keep in sync.
+- **One API everywhere.** The same syntax runs on PostgreSQL, MySQL, MariaDB, SQLite, LibSQL, Neon, Cloudflare D1, MongoDB, and Bun's native SQL.
+- **Fast by design.** Fastest in [all 8 categories](https://uql-orm.dev/benchmark) of our [open benchmark](https://github.com/rogerpadilla/ts-orm-benchmark): on average ~2.1× faster than the runner-up, reaching 3.5M ops/s on SELECTs and DELETEs.
 
 ## Features
 
-| Feature | Why it matters |
+| Feature | Docs |
 | :--- | :--- |
-| **[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** | 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 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 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
-
-Install the core package and the driver for your database:
+| Unified API across SQL + MongoDB | [Install](https://uql-orm.dev/getting-started) |
+| Type-safe queries with autocomplete | [Querying](https://uql-orm.dev/querying/querier) |
+| Entity-first migrations & autoSync | [Migrations](https://uql-orm.dev/migrations) |
+| Soft-delete, lifecycle hooks, relations | [Entities](https://uql-orm.dev/entities/basic) |
+| Aggregate queries, grouping, HAVING | [Aggregate](https://uql-orm.dev/querying/aggregate) |
+| Semantic search & vector similarity | [Semantic Search](https://uql-orm.dev/ai-semantic-search) |
+| Streaming, transactions, raw SQL | [Querying](https://uql-orm.dev/querying/querier) |
+| NestJS integration & HttpQuerier | [Fullstack](https://uql-orm.dev/comparison) |
 
-```sh
-# Core
-npm install uql-orm       # or bun add / pnpm add
-```
-
-### Supported Drivers (pick according to your database)
+## Install
 
-| Database | Command |
-| :--- | :--- |
-| **PostgreSQL** (incl. Neon, Cockroach, Yugabyte) | `npm install pg` |
-| **MySQL** (incl. TiDB, Aurora) | `npm install mysql2` |
-| **MariaDB** | `npm install mariadb` |
-| **SQLite** | `npm install better-sqlite3` |
-| **LibSQL** (incl. Turso) | `npm install @libsql/client` |
-| **MongoDB** | `npm install mongodb` |
-| **Cloudflare D1** | _Native (no driver needed)_ |
-| **Bun SQL Native** (Incl. Postgres, MySQL, SQLite) | _Native (via `bun:sql`)_ |
-
-### TypeScript Configuration
-
-If you use the **decorator-based approach**, make sure your `tsconfig.json` is configured to support decorators and metadata:
-
-
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}
+```sh
+npm install uql-orm pg   # or mysql2, mariadb, better-sqlite3, mongodb, @libsql/client
 ```
 
-> **Note:** UQL is Modern Pure ESM — ensure your project's `module` supports ESM imports (e.g., `NodeNext`, `ESNext`, `Bundler`).
+Supports PostgreSQL, MySQL, MariaDB, SQLite, CockroachDB, LibSQL/Turso, Neon, MongoDB, Cloudflare D1, and Bun SQL.
 
-## 2. Define your Entities
+## Define Entities
 
-[Declare](https://uql-orm.dev/entities/basic) your classes with decorators, or use the [imperative](https://uql-orm.dev/entities/imperative) approach for decorator-free registration. UQL's engine uses this metadata for both type-safe querying and precise DDL generation. This includes the new **`defineEntity`** API which works without requiring `experimentalDecorators` in your `tsconfig.json`.
-
-### Core Decorators
-
-| Decorator | Purpose |
-| :--- | :--- |
-| `@Entity()` | Marks a class as a database table/collection. |
-| `@Id()` | Defines the Primary Key with support for `onInsert` generators. |
-| `@Field()` | Standard column. Use `{ references: ... }` for Foreign Keys. |
-| `@Index()` | Defines a composite or custom index on one or more columns. |
-| `@OneToOne` | Defines a one-to-one relationship. |
-| `@OneToMany` | Defines a one-to-many relationship. |
-| `@ManyToOne` | Defines a many-to-one relationship. |
-| `@ManyToMany` | Defines a many-to-many relationship. |
-| `@BeforeInsert` | Lifecycle hooks fired around database operations. |
-| `@AfterLoad` | Lifecycle hook fired after loading entities. |
-
-### Type Abstraction: Logical vs. Physical
-
-UQL separates the **intent** of your data from its **storage**. Both properties are **optional**; if omitted, UQL performs a *best-effort inference* using the TypeScript types from your class.
-
-| Property | Purpose | Values |
-| :--- | :--- | :--- |
-| **`type`** | **Logical Type** (Abstraction). Used for runtime behavior and automatic SQL mapping. | `String`, `Number`, `Boolean`, `Date`, `BigInt`, or semantic strings: `'uuid'`, `'json'`, `'vector'`, `'halfvec'`, `'sparsevec'`. |
-| **`columnType`** | **Physical Type** (Implementation). **Highest Priority**. Bypasses UQL's inference for exact SQL control. | Raw SQL types: `'varchar(100)'`, `'decimal(10,2)'`, `'smallint'`, etc. |
-
-```ts
-// Automatic inference from TypeScript types
-@Field() name?: string;           // → TEXT (Postgres), VARCHAR(255) (MySQL)
-@Field() age?: number;            // → INTEGER
-@Field() isActive?: boolean;      // → BOOLEAN
-@Field() createdAt?: Date;        // → TIMESTAMP
-
-// Semantic types - portable across all databases
-@Field({ type: 'uuid' })          // → UUID (Postgres), CHAR(36) (MySQL), TEXT (SQLite)
-externalId?: string;
-
-@Field({ type: 'json' })          // → JSONB (Postgres), JSON (MySQL), TEXT (SQLite)
-metadata?: Json<{ theme?: string }>;
-
-// Logical types with constraints - portable with control
-@Field({ type: 'varchar', length: 500 })
-bio?: string;
-
-@Field({ type: 'decimal', precision: 10, scale: 2 })
-price?: number;
-
-// Exact SQL type - when you need dialect-specific control
-@Field({ columnType: 'smallint' })
-statusCode?: number;
-```
-
-> **Note:** Use the `Relation<T>` utility type for relationship properties. It prevents TypeScript circular dependency errors while maintaining full type-safety throughout your app.
+[Declare](https://uql-orm.dev/entities/basic) your classes with decorators. UQL uses this metadata for type-safe querying and DDL generation.
 
 ```ts
 import { v7 as uuidv7 } from 'uuid';
-import { Entity, Id, Field, OneToOne, OneToMany, ManyToOne, ManyToMany, type Relation, type Json } from 'uql-orm';
+import { Entity, Id, Field, OneToOne, OneToMany, type Relation } from 'uql-orm';
 
 @Entity()
 export class User {
   @Id({ type: 'uuid', onInsert: () => uuidv7() })
   id?: string;
 
-  @Field({
-    index: true,
-  })
-  name?: string;
-
-  @Field({
-    unique: true,
-    comment: 'User login email',
-  })
+  @Field({ index: true, unique: true })
   email?: string;
 
-  @OneToOne({
-    entity: () => Profile,
-    mappedBy: (profile) => profile.user,
-    cascade: true,
-  })
+  @OneToOne({ entity: () => Profile, mappedBy: (p) => p.user, cascade: true })
   profile?: Relation<Profile>;
 
-  @OneToMany({
-    entity: () => Post,
-    mappedBy: (post) => post.author,
-  })
+  @OneToMany({ entity: () => Post, mappedBy: (p) => p.author })
   posts?: Relation<Post>[];
 }
-
-@Entity()
-export class Profile {
-  @Id({ type: 'uuid', onInsert: () => uuidv7() })
-  id?: string;
-
-  @Field()
-  bio?: string;
-
-  @Field({ references: () => User, foreignKey: 'fk_profile_user' })
-  userId?: string;
-
-  @OneToOne({ entity: () => User })
-  user?: User;
-}
-
-@Entity()
-export class Post {
-  @Id()
-  id?: number;
-
-  @Field()
-  title?: string;
-
-  @Field({ references: () => User })
-  authorId?: string;
-
-  @ManyToOne({ entity: () => User })
-  author?: User;
-
-  @ManyToMany({
-    entity: () => Tag,
-    through: () => PostTag,
-  })
-  tags?: Tag[];
-}
-
-@Entity()
-export class Tag {
-  @Id({ type: 'uuid', onInsert: () => uuidv7() })
-  id?: string;
-
-  @Field()
-  name?: string;
-}
-
-@Entity()
-export class PostTag {
-  @Id({ type: 'uuid', onInsert: () => uuidv7() })
-  id?: string;
-
-  @Field({ references: () => Post })
-  postId?: number;
-
-  @Field({ references: () => Tag })
-  tagId?: string;
-}
-
-### Alternative: Imperative (Decorator-free) Definition
-
-If you prefer a functional approach or are in an environment where decorators are disabled (e.g., some edge runtimes or specific build pipelines), you can register entities imperatively using `defineEntity`. **Crucially, this approach works without requiring `experimentalDecorators` or `emitDecoratorMetadata` in your `tsconfig.json`.**
-
-This API supports bulk configuration of `fields`, `relations`, `indexes`, and `hooks` directly within the options object. UQL also exports helper functions like `defineField`, `defineId`, and `defineRelation` to assist with type-safe imperative setup.
-
-```ts
-import { defineEntity } from 'uql-orm';
-
-class User {}
-
-defineEntity(User, {
-  name: 'users',
-  fields: {
-    id: { type: 'uuid', isId: true },
-    name: { type: String },
-    email: { type: String, unique: true },
-  },
-
-  indexes: [
-    { columns: ['email'], unique: true },
-  ],
-  // You can also define hooks and relations here
-});
-```
-```
-
-
-## 3. Set up a pool
-
-A pool manages connections (queriers). Initialize it once at application bootstrap (e.g., in `server.ts`).
-
-```ts
-import { SnakeCaseNamingStrategy, type Config } from 'uql-orm';
-import { PgQuerierPool } from 'uql-orm/postgres'; // or mysql2, sqlite, bunSql, etc.
-import { User, Profile, Post } from './entities';
-
-export const pool = new PgQuerierPool(
-  { host: 'localhost', database: 'uql_app', max: 10 },
-  {
-    logger: ['error', 'warn', 'migration'],
-    namingStrategy: new SnakeCaseNamingStrategy(),
-    slowQuery: { threshold: 1000 },
-  }
-);
-
-export default {
-  pool,
-  entities: [User, Profile, Post],
-  migrationsPath: './migrations',
-} satisfies Config;
-```
-
-> **Notes:**
-> - Reuse one pool for both app queries and migrations to keep behavior (for example naming strategy) consistent.
-> - **LibSQL embedded replica** (`file:` + `syncUrl`): `LibsqlQuerierPool` runs **migrations and the `uql_migrations` table** against **`syncUrl`**, while **`getQuerier`** stays on the local file. **`getDiffs` / introspection** (e.g. `generate:entities`) still use the normal pool connection—often the local replica—so compare with your remote if needed.
-> - If your architecture spans backend + browser, `HttpQuerier` reduces custom API mapping and keeps query semantics aligned.
-> - **Upgrading:** use `pool.dialect` (not `pool.dialectInstance`), read `pool.dialect.dialectName`, and remove any top-level `dialect` from migrate config (see `CHANGELOG.md`).
-
-### Driver → pool → dialect class
-
-Migrations and the CLI read **`pool.dialect.dialectName`** only (there is no separate top-level `dialect` in config). Pick the pool (and thus the dialect class) for your driver.
-
-| Import path | Pool class | Dialect class (on the pool) | Notes |
-| :--- | :--- | :--- | :--- |
-| `uql-orm/postgres` | `PgQuerierPool` | `PgDialect` | Node `pg`; base Postgres capabilities (native arrays, `$n::jsonb`). |
-| `uql-orm/postgres` | — | `PostgresDialect` | Base Postgres AST; subclass for other Postgres wire drivers. |
-| `uql-orm/neon` | `NeonQuerierPool` | `NeonDialect` | `@neondatabase/serverless`; extends `PostgresDialect` with Neon-oriented defaults. |
-| `uql-orm/cockroachdb` | `CrdbQuerierPool` | `CockroachDialect` | `dialectName` is `cockroachdb`; extends `PostgresDialect`. |
-| `uql-orm/mysql` | `Mysql2QuerierPool` | `MySql2Dialect` | `mysql2` driver. |
-| `uql-orm/maria` | `MariadbQuerierPool` | `MariaDialect` | `mariadb` driver. |
-| `uql-orm/sqlite` | `Sqlite3QuerierPool` | `BetterSqlite3Dialect` | `better-sqlite3` (or Bun SQLite in that pool). |
-| `uql-orm/libsql` | `LibsqlQuerierPool` | `LibsqlDialect` | `@libsql/client`. |
-| `uql-orm/d1` | `D1QuerierPool` | `D1SqliteDialect` | Cloudflare D1. |
-| `uql-orm/mongo` | `MongodbQuerierPool` | `MongodbNativeDialect` | Official `mongodb` driver. |
-| `uql-orm/bunSql` | `BunSqlQuerierPool` | _inferred_ | Dialect class chosen from `SQL.Options` (Postgres / MySQL / MariaDB / SQLite / Cockroach). |
-
-For **wire-level** differences on PostgreSQL (e.g. Bun SQL vs `pg`), `BunSqlPostgresDialect` merges `POSTGRES_WIRE_DRIVER_CAPABILITIES` from `uql-orm/postgres/wireCapabilities` (array literals + JSON text cast); `PgDialect` does not.
-
-## 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 },
-    $populate: { profile: { $select: { bio: true }, $required: true } }, // INNER JOIN
-    $where: {
-      status: 'active',
-      name: { $istartsWith: 'a' },
-    },
-    $limit: 10,
-  });
-} finally {
-  await querier.release(); // Always release back to the pool
-}
-```
-
-**Generated SQL (PostgreSQL):**
-
-```sql
-SELECT "User"."name", "profile"."id" AS "profile_id", "profile"."bio" AS "profile_bio"
-FROM "User"
-INNER JOIN "Profile" AS "profile" ON "profile"."userId" = "User"."id"
-WHERE "User"."status" = 'active' AND "User"."name" ILIKE 'a%'
-LIMIT 10 OFFSET 0
-```
-
-### Projection & Relation Loading
-
-Use these query keys with clear separation of concerns:
-
-- `$select`: scalar field whitelist (projection)
-- `$exclude`: scalar field subtraction from default eager set
-- `$populate`: relation loading (including nested relation query options)
-
-`$select` and `$exclude` are mutually exclusive when `$select` includes positive scalar keys.
-
-```ts
-const rows = await querier.findMany(User, {
-  $exclude: { password: true },
-  $populate: { profile: { $select: { picture: true } } },
-});
-```
-
-> **Migration note:** selecting relations inside `$select` is still supported for backward compatibility, but deprecated. Move relations to `$populate`.
-
-### Streaming (`findManyStream`) and relations
-
-`findManyStream` is optimized for **scalar** reads and a stable memory footprint. Relation loading differs by backend:
-
-- **SQL:** Joinable relations (e.g. many-to-one, one-to-one) are still included in the streamed `SELECT` / joins. **To-many** collections are not filled on the stream path (that uses extra queries in `findMany`); requesting them in `$select` / `$populate` throws a `TypeError` with a short explanation.
-- **MongoDB:** Streams use a plain `find` cursor, so **any** relation keys in `$select` or `$populate` throw a `TypeError`. Use `findMany` for relation loading (aggregation + fill).
-
-See [Cursor Streaming](https://uql-orm.dev/querying/streaming) on the docs site for details.
-
-### 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
-
-Define complex logic directly in your entities using `raw` functions. These are resolved during SQL generation for peak efficiency.
-
-```ts
-@Entity()
-export class Item {
-  @Field({
-    virtual: raw(({ ctx, dialect, escapedPrefix }) => {
-      ctx.append('(');
-      dialect.count(ctx, ItemTag, {
-        $where: { itemId: raw(({ ctx }) => ctx.append(`${escapedPrefix}.id`)) }
-      }, { autoPrefix: true });
-      ctx.append(')');
-    })
-  })
-  tagsCount?: number;
-}
 ```
 
-### JSON 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 native SQL per 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`
-**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
-// 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))`
-
-> **Note:** Wrap JSON fields with `Json<T>` to get autocompletion for valid dot-notation paths.
-
-### Aggregate Queries
+> **Imperative API:** `defineEntity(User, { fields: { id: { type: 'uuid', isId: true } }, ... })`. No decorators needed. See [Imperative Definition](https://uql-orm.dev/entities/imperative).
 
-Use `querier.aggregate()` for `GROUP BY` analytics with `$count`, `$sum`, `$avg`, `$min`, `$max`, and full `$having` support.
+## Querying
 
 ```ts
-const results = await querier.aggregate(Order, {
-  $group: {
-    status: true,
-    total: { $sum: 'amount' },
-    count: { $count: '*' },
-  },
-  $having: { count: { $gt: 5 } },
-  $sort: { total: -1 },
+await querier.findMany(User, {
+  $select: { id: true, name: true },
+  $where: { email: { $endsWith: '@uql-orm.dev' } },
   $limit: 10,
 });
 ```
 
-**Generated SQL (PostgreSQL):**
+25+ comparison operators (`$eq`, `$in`, `$between`, `$like`, `$elemMatch`), logical operators (`$and`, `$or`, `$not`, `$nor`), and type-safe JSON/JSONB dot-notation queries.
 
-```sql
-SELECT "status", SUM("amount") "total", COUNT(*) "count"
-FROM "Order"
-GROUP BY "status"
-HAVING COUNT(*) > $1
-ORDER BY SUM("amount") DESC
-LIMIT 10
-```
-
-For `SELECT DISTINCT`, add `$distinct: true` to any find query:
-
-```ts
-const names = await querier.findMany(User, {
-  $select: { name: true },
-  $distinct: true,
-});
-// → SELECT DISTINCT "name" FROM "User"
-```
-
-> **Learn more**: See the full [Aggregate Queries guide](https://uql-orm.dev/querying/aggregate) for `$having` operators, MongoDB pipeline details, and advanced patterns.
-
-### 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.
-
-```ts
-for await (const user of querier.findManyStream(User, { $where: { active: true } })) {
-  process.stdout.write(JSON.stringify(user) + '\n');
-}
-```
+> [Querying](https://uql-orm.dev/querying/querier) · [Operators](https://uql-orm.dev/querying/comparison-operators) · [JSON](https://uql-orm.dev/querying/json)
 
-### Thread-Safe Transactions
+## Transactions
 
-UQL is one of the few ORMs with a **centralized serialization engine**. Transactions are guaranteed to be race-condition free.
-
-#### Option A: Manual (Functional)
+Functional `pool.transaction()` or `@Transactional()` decorator with centralized serialization:
 
 ```ts
-const result = await pool.transaction(async (querier) => {
-  const user = await querier.findOne(User, { $where: { email: '...' } });
-  await querier.insertOne(Profile, { userId: user.id, bio: '...' });
+const userId = await pool.transaction(async (q) => {
+  const id = await q.insertOne(User, { email: 'a@b.com' });
+  await q.insertOne(Profile, { userId: id, bio: '...' });
+  return id;
 });
 ```
 
-#### Option B: Declarative (Decorators)
-
-Perfect for **NestJS** and other Dependency Injection frameworks. Use `@Transactional()` to wrap a method and `@InjectQuerier()` to access the managed connection.
-
-```ts
-import { Transactional, InjectQuerier, type Querier } from 'uql-orm';
-
-export class UserService {
-  @Transactional()
-  async register({picture, ...user}: UserProfile, @InjectQuerier() querier?: Querier) {
-    const userId = await querier.insertOne(User, user);
-    await querier.insertOne(Profile, { userId, picture });
-  }
-}
-```
-
-#### Option C: Imperative
-
-For granular control over the transaction lifecycle, manage `begin`, `commit`, `rollback`, and `release` yourself.
-
-```ts
-const querier = await pool.getQuerier();
-try {
-  await querier.beginTransaction();
-
-  const userId = await querier.insertOne(User, { name: '...' });
-  await querier.insertOne(Profile, { userId, picture: '...' });
-
-  await querier.commitTransaction();
-} catch (error) {
-  await querier.rollbackTransaction();
-  throw error;
-} finally {
-  await querier.release();
-}
-```
-
-## 5. Migrations & Synchronization
+## Migrations
 
-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.
+Entity-first migrations: modify TypeScript classes, UQL auto-generates DDL by diffing code against the live database:
 
 ```bash
-# 1. Update your entity (add a field, change a type, etc.)
-# 2. Auto-generate the migration
-npx uql-migrate generate:entities add_user_nickname
-
-# 3. Review and apply
-npx uql-migrate up
-```
-
-> **Note:** Keep entities as the source of truth to minimize drift between code and database schema.
-
-**Generated `generate:entities` files** emit **one `await querier.run("…")` per SQL statement** (table vs indexes, etc.), with the SQL passed as a **double-quoted string literal** (`JSON.stringify`) so dialects that quote identifiers with **backticks** (SQLite, LibSQL, MySQL-style) do not produce invalid TypeScript.
-
-If you implement a **custom `SchemaGenerator`**, note that **`generateCreateTable`**, **`generateCreateTableFromNode`**, and **`generateCreateTableFromDefinition`** return **`string[]`** (one entry per `querier.run`). Use **`.join('\n')`** only when you need a single combined script. See the **[changelog](CHANGELOG.md)** for **0.8.2**.
-
-**Advanced:** custom tools can use **`acquireQuerierForMigrations(pool)`** from **`uql-orm/migrate`** to match the same connection choice as **`Migrator`** and **`DatabaseMigrationStorage`** (including optional **`pool.getMigrationQuerier`**).
-
-### 1. Unified Configuration
-
-Reuse the same `uql.config.ts` for your app and the CLI to ensure consistent settings (naming strategies, entities, pool):
-
-```ts
-// uql.config.ts
-import type { Config } from 'uql-orm';
-import { PgQuerierPool } from 'uql-orm/postgres';
-import { User, Profile, Post } from './entities';
-
-export default {
-  pool: new PgQuerierPool({ /* ... */ }),
-  entities: [User, Profile, Post],
-  migrationsPath: './migrations',
-} satisfies Config;
+npx uql-migrate generate:entities add_user_nickname   # generate from entities
+npx uql-migrate up                                      # apply
+npx uql-migrate drift:check                             # detect drift
 ```
 
-### 2. Manage via CLI
-
-Use the CLI to manage your database schema evolution.
-
-| Command | Description |
-| :--- | :--- |
-| `generate:entities <name>` | **Auto-generates** a migration by diffing your entities against the current DB schema. |
-| `generate <name>` | Creates an empty timestamped file for **manual** SQL migrations (e.g., data backfills). |
-| `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. |
-
-#### Usage Examples
-
-```bash
-# 1. Auto-generate schema changes from your entities
-npx uql-migrate generate:entities add_profile_table
-
-# 2. Apply changes
-npx uql-migrate up
-
-# 3. Check for schema drift (Production Safety)
-npx uql-migrate drift:check
-
-# 4. Scaffold entities from an existing DB (Legacy Adoption)
-npx uql-migrate generate:from-db --output ./src/entities
-
-# 5. Create a manual migration (for data backfills or custom SQL)
-npx uql-migrate generate seed_default_roles
-```
-
-> **Bun Users**: If your `uql.config.ts` uses TypeScript path aliases (e.g., `~app/...`), run migrations with the `--bun` flag to ensure proper resolution:
-> ```bash
-> bun run --bun uql-migrate status
-> ```
-> Or add a script to your `package.json`: `"uql": "bun run --bun uql-migrate"`, then run commands like, e.g., `bun run uql status`.
-
-### 3. AutoSync (Development)
-
-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 (e.g., dropping a column or changing a `VARCHAR` to an `INTEGER`). Blocked actions are logged so you can migrate them 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)**
-
-If you follow the [unified configuration](#1-unified-configuration) pattern, your entities are already imported. Simply reuse it:
-
-```ts
-import { Migrator } from 'uql-orm/migrate';
-import config from './uql.config.js';
-
-const migrator = new Migrator(config.pool, {
-  entities: config.entities,
-});
-await migrator.autoSync({ logging: true });
-```
-
-**Explicit Entities**
-
-Alternatively, pass entities directly if you want to be explicit about which entities to sync:
-
-```ts
-import { Migrator } from 'uql-orm/migrate';
-import { User, Profile, Post } from './entities/index.js';
-
-const migrator = new Migrator(pool, {
-  entities: [User, Profile, Post],
-});
-await migrator.autoSync({ logging: true });
-```
-
-> **Note:** In development, `autoSync` accelerates iteration while still protecting data by blocking destructive schema changes.
-
-## 6. Operations
-
-### 6.1 Logging & Monitoring
-
-UQL includes a structured logging system for query visibility and performance monitoring.
-
-### Log Levels
-
-| Level                 | Description                                                                             |
-| :-------------------- | :-------------------------------------------------------------------------------------- |
-| `query`             | **Standard Queries**: Beautifully formatted SQL/Command logs with execution time. |
-| `slowQuery`         | **Bottleneck Alerts**: Dedicated logging for queries exceeding your threshold. Use `logParams: false` to omit sensitive data. |
-| `error` / `warn`  | **System Health**: Detailed error traces and potential issue warnings.            |
-| `migration`         | **Audit Trail**: Step-by-step history of schema changes.                          |
-| `skippedMigration`  | **Safety**: Logs blocked unsafe schema changes during autoSync.                   |
-| `schema` / `info` | **Lifecycle**: Informative logs about ORM initialization and sync events.         |
-
-### Visual Feedback
-
-The `DefaultLogger` provides high-contrast, colored output for quick debugging:
-
-```text
-query: SELECT * FROM "user" WHERE "id" = $1 -- [123] [2ms]
-slow query: UPDATE "post" SET "title" = $1 -- ["New Title"] [1250ms]
-error: Failed to connect to database: Connection timeout
-```
-
-> **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:
+Safe `autoSync()` mode adds new tables/columns and blocks destructive changes in development.
 
-- [Complex Logical Operators](https://uql-orm.dev/querying/logical-operators)
-- [Aggregate Queries (GROUP BY, HAVING, DISTINCT)](https://uql-orm.dev/querying/aggregate)
-- [Semantic Search (Vector Similarity)](https://uql-orm.dev/querying/semantic-search)
-- [Relationship Mapping (1-1, 1-M, M-M)](https://uql-orm.dev/querying/relations)
-- [Lifecycle Hooks](https://uql-orm.dev/entities/lifecycle-hooks)
-- [Soft Deletes &amp; Auditing](https://uql-orm.dev/entities/soft-delete)
-- [Database Migration &amp; Syncing](https://uql-orm.dev/migrations)
+> [Migrations](https://uql-orm.dev/migrations)
 
-### Deep Dive: Tests & Technical Resources
+---
 
-For those who want to see the "engine under the hood," check out these resources in the source code:
+## Made with UQL
 
-- **Entity Mocks**: See how complex entities and virtual fields are defined in [entityMock.ts](https://github.com/rogerpadilla/uql/blob/main/packages/uql-orm/src/test/entityMock.ts).
-- **Core Dialect Logic**: The foundation of our context-aware SQL generation in [abstractSqlDialect.ts](https://github.com/rogerpadilla/uql/blob/main/packages/uql-orm/src/dialect/abstractSqlDialect.ts).
-- **Comprehensive Test Suite**:
-  - [Abstract SQL Spec](https://github.com/rogerpadilla/uql/blob/main/packages/uql-orm/src/dialect/abstractSqlDialect-spec.ts): Base test suite for all dialects.
-  - [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.
+### [Variability.ai](https://variability.ai)
 
-## Built with ❤️ and supported by
+AI meeting recorder and video summarizer for Zoom, Meet, Teams, and more. Generates instant summaries with action items in 45+ languages.
 
-UQL is an open-source project proudly sponsored by **[Variability.ai](https://variability.ai)**.
+[![Made with UQL](https://img.shields.io/badge/made%20with-UQL-6e6e6e?style=flat)](https://uql-orm.dev)