@uql/core 3.4.2 → 3.4.4

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.4.2](https://github.com/rogerpadilla/uql/compare/@uql/core@3.4.1...@uql/core@3.4.2) (2025-12-31)
+## [3.4.4](https://github.com/rogerpadilla/uql/compare/@uql/core@3.4.3...@uql/core@3.4.4) (2025-12-31)
 
 **Note:** Version bump only for package @uql/core
 
@@ -17,6 +17,11 @@ All notable changes to this project will be documented in this file. Please add
 
 date format is [yyyy-mm-dd]
 
+## [3.4.1]
+### Improve documentation
+
+- Update examples in docs
+
 ## [3.1.1](https://github.com/rogerpadilla/uql/compare/@uql/core@3.1.0...@uql/core@3.1.1) (2025-12-30)
 ### Bug Fixes
 * adjust relative paths for README and CHANGELOG in copyfiles script ([741c2ee](https://github.com/rogerpadilla/uql/commit/741c2ee8839376ca89a860a53950ef6b6d234596))

package/README.md

@@ -12,7 +12,7 @@
  
 
 ```ts
-const companyUsers = await userRepository.findMany({
+const users = await querier.findMany(User, {
   $select: { email: true, profile: { $select: { picture: true } } },
   $where: { email: { $endsWith: '@domain.com' } },
   $sort: { createdAt: 'desc' },
@@ -24,22 +24,22 @@ const companyUsers = await userRepository.findMany({
 
 ## Why UQL?
 
-See [this article](https://medium.com/@rogerpadillac/in-search-of-the-perfect-orm-e01fcc9bce3d) in medium.com.
+See [this article](https://medium.com/@rogerpadillac/in-search-of-the-perfect-orm-e01fcc9bce3d) on medium.com.
 
  
 
 ## Features
 
-- **Type-safe and Context-aware queries**: Squeeze the power of `TypeScript` for auto-completion and validation of operators at any depth, [including relations and their fields](https://www.uql.app/docs/querying-relations).
+- **Type-safe and Context-aware queries**: Squeeze all the power of `TypeScript` for auto-completion and validation of operators at any depth, [including relations and their fields](https://www.uql.app/querying/relations).
 - **Context-Object SQL Generation**: Uses a sophisticated `QueryContext` pattern to ensure perfectly indexed placeholders ($1, $2, etc.) and robust SQL fragment management, even in the most complex sub-queries.
 - **Unified API across Databases**: Write once, run anywhere. Seamlessly switch between `PostgreSQL`, `MySQL`, `MariaDB`, `SQLite`, `LibSQL`, `Neon`, `Cloudflare D1`, and even `MongoDB`.
 - **Serializable JSON Syntax**: Queries can be expressed as `100%` valid `JSON`, allowing them to be easily transported from frontend to backend.
 - **Naming Strategies**: Effortlessly translate between TypeScript `CamelCase` and database `snake_case` (or any custom format) with a pluggable system.
-- **Built-in Serialization**: A centralized task queue and `@Serialized()` decorator ensure database operations are thread-safe and race-condition free by default.
+- **Built-in Serialization**: A centralized task queue and the `@Serialized()` decorator ensure that database operations are thread-safe and race-condition-free by default.
 - **Database Migrations**: Integrated migration system for version-controlled schema management and auto-generation from entities.
 - **High Performance**: Optimized "Sticky Connections" and human-readable, minimal SQL generation.
 - **Modern Architecture**: Pure `ESM` support, designed for `Node.js`, `Bun`, `Deno`, and even mobile/browser environments.
-- **Rich Feature Set**: [Soft-delete](https://uql.app/docs/entities-soft-delete), [virtual fields](https://uql.app/docs/entities-virtual-fields), [repositories](https://uql.app/docs/querying-repository), and automatic handling of `JSON`, `JSONB`, and `Vector` types.
+- **Rich Feature Set**: [Soft-delete](https://www.uql.app/entities/soft-delete/), [virtual fields](https://uql.app/entities/virtual-fields), [repositories](https://uql.app/querying/repository), and automatic handling of `JSON`, `JSONB`, and `Vector` types.
 
  
 
@@ -65,9 +65,8 @@ See [this article](https://medium.com/@rogerpadillac/in-search-of-the-perfect-or
 | `LibSQL` (Turso) | `@libsql/client`
 | `Neon` (Serverless Postgres) | `@neondatabase/serverless`
 
- 
 
-For example, for `Postgres` install the `pg` driver:
+For example, for `Postgres`, install the `pg` driver:
 
 ```sh
 npm install pg
@@ -83,7 +82,7 @@ bun add pg
    "emitDecoratorMetadata": true
    ```
 
-> **Note**: `"ES2022"`, `"ES2023"`, or `"ESNext"` will also work fine for `target`.
+> **Note**: `"ES2022"`, `"ES2023"`, or `"ESNext"` will also work fine for the `target`.
 
 ---
 
@@ -172,9 +171,25 @@ export class PostTag {
 
  
 
-## 3. Setup a querier-pool
+## 3. Set up a pool (of queriers)
+
+A pool is an abstraction that manages connections (queriers) to your database. A querier is an abstraction that represents a connection to the database.
+
+The pool can be set in any of the bootstrap files of your app (e.g., in `server.ts`).
+
+### Available built-in QuerierPool classes per database
+
+| Database | QuerierPool class
+| :--- | :---
+| `PostgreSQL` (incl. CockroachDB, YugabyteDB) | `@uql/core/postgres/PgQuerierPool`
+| `MySQL` (incl. TiDB, Aurora) | `@uql/core/mysql/Mysql2QuerierPool`
+| `MariaDB` | `@uql/core/maria/MariadbQuerierPool`
+| `SQLite` | `@uql/core/sqlite/SqliteQuerierPool`
+| `Cloudflare D1` | `@uql/core/d1/D1QuerierPool`
+| `LibSQL` (Turso) | `@uql/core/libsql/LibsqlQuerierPool`
+| `Neon` (Serverless Postgres) | `@uql/core/neon/NeonQuerierPool`
 
-A querier-pool can be set in any of the bootstrap files of your app (e.g. in the `server.ts`).
+### Example of setting up a pool for PostgreSQL
 
 ```ts
 // file: ./shared/orm.ts
@@ -190,12 +205,13 @@ export const pool = new PgQuerierPool(
     min: 1,
     max: 10,
   },
-  // Optional extra options.
+  // Extra options (optional).
   {
-    // Optional, any custom logger function can be passed here (optional).
+    // Pass any custom logger function here (optional).
     logger: console.debug,
-    // Automatically translate between TypeScript camelCase and database snake_case.
+    // Pass a naming strategy here (optional, by default no automatic names translation).
     // This affects both queries and schema generation.
+    // E.g. `SnakeCaseNamingStrategy` automatically translate between TypeScript camelCase and database snake_case.
     namingStrategy: new SnakeCaseNamingStrategy()
   },
 );
@@ -205,7 +221,7 @@ export const pool = new PgQuerierPool(
 
 ## 4. Manipulate the data
 
-UQL provides multiple ways to interact with your data, from generic `Queriers` (that works with any entity) to entity-specific `Repositories`.
+UQL provides multiple ways to interact with your data, from generic `Queriers` (that work with any entity) to entity-specific `Repositories`.
 
 ```ts
 import { User } from './shared/models/index.js';
@@ -227,8 +243,9 @@ try {
       email: { $iincludes: '@example.com' }, // Case-insensitive search
       status: 'active'
     },
-    $sort: { createdAt: -1 },
-    $limit: 50
+    $sort: { createdAt: 'desc' },
+    $skip: 10
+    $limit: 10,
   });
 } finally {
   // Always release the querier to the pool
@@ -261,8 +278,7 @@ try {
         $select: ['title', 'createdAt'],
         // Filter the related collection directly
         $where: { title: { $iincludes: 'typescript' } },
-        $sort: { createdAt: -1 },
-        $limit: 5
+        $sort: { createdAt: 'desc' },
       }
     },
     $where: {
@@ -319,14 +335,14 @@ const result = await pool.transaction(async (querier) => {
   const profileId = await querier.insertOne(Profile, { userId: user.id, ... });
   return { userId: user.id, profileId };
 });
-// Connection is automatically released after transaction
+// Connection is automatically released after a transaction.
 ```
 
  
 
 ## 5. Migrations & Synchronization
 
-UQL includes a robust migration system and an "Entity-First" synchronization engine built directly into the core.
+UQL includes a robust *migration system* and an *Entity-First auto-synchronization* engine built directly into the core.
 
 ### 1. Create Configuration
 
@@ -369,9 +385,9 @@ npx uql-migrate status
 bunx uql-migrate status
 ```
 
-### 3. Entity-First Synchronization (Development)
+### 3. Entity-First Synchronization (recommended for development)
 
-In development, you can use `autoSync` to automatically keep your database in sync with your entities without manual migrations. It is **safe by default**, meaning it only adds missing tables and columns.
+We recommend using `autoSync` (in development) to automatically keep your database in sync with your entities, eliminating the need for manual migrations. It is **safe by default**, meaning it only adds missing tables and columns.
 
 ```ts
 import { Migrator } from '@uql/core/migrate';
@@ -381,15 +397,15 @@ const migrator = new Migrator(pool);
 await migrator.autoSync({ logging: true });
 ```
 
-Check out the full [documentation](https://uql.app/docs/migrations) for detailed CLI commands and advanced usage.
+Check out the full [documentation](https://uql.app/migrations) for detailed CLI commands and advanced usage.
 
  
 
-Check out the full documentation at [uql.app](https://uql.app) for details on:
-- [Complex Logical Operators](https://uql.app/docs/querying-logical-operators)
-- [Relationship Mapping (1-1, 1-M, M-M)](https://uql.app/docs/querying-relations)
-- [Soft Deletes & Auditing](https://uql.app/docs/entities-soft-delete)
-- [Database Migration & Syncing](https://uql.app/docs/migrations)
+Learn more about UQL at [uql.app](https://uql.app) for details on:
+- [Complex Logical Operators](https://uql.app/querying/logical-operators)
+- [Relationship Mapping (1-1, 1-M, M-M)](https://uql.app/querying/relations)
+- [Soft Deletes & Auditing](https://uql.app/entities/soft-delete)
+- [Database Migration & Syncing](https://uql.app/migrations)
 
 ---
 
@@ -403,7 +419,6 @@ For those who want to see the "engine under the hood," check out these resources
   - [Abstract SQL Spec](https://github.com/rogerpadilla/uql/blob/main/packages/core/src/dialect/abstractSqlDialect-spec.ts): The base test suite shared by all dialects.
   - [PostgreSQL Spec](https://github.com/rogerpadilla/uql/blob/main/packages/core/src/postgres/postgresDialect.spec.ts) | [MySQL Spec](https://github.com/rogerpadilla/uql/blob/main/packages/core/src/mysql/mysqlDialect.spec.ts) | [SQLite Spec](https://github.com/rogerpadilla/uql/blob/main/packages/core/src/sqlite/sqliteDialect.spec.ts).
   - [Querier Integration Tests](https://github.com/rogerpadilla/uql/blob/main/packages/core/src/querier/abstractSqlQuerier-spec.ts): Testing the interaction between SQL generation and connection management.
-  - [MongoDB Migration Tests](https://github.com/rogerpadilla/uql/blob/main/packages/core/src/migrate/migrator-mongo.it.ts): Integration tests ensuring correct collection and index synchronization for MongoDB.
 
 ---