uql-orm 0.5.0 → 0.5.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +13 -18
- package/README.md +72 -56
- package/package.json +6 -6
package/CHANGELOG.md
CHANGED
|
@@ -1,27 +1,22 @@
|
|
|
1
|
-
# Change Log
|
|
2
|
-
|
|
3
|
-
All notable changes to this project will be documented in this file.
|
|
4
|
-
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
|
5
|
-
|
|
6
|
-
# [0.5.0](https://github.com/rogerpadilla/uql/compare/uql-orm@0.4.5...uql-orm@0.5.0) (2026-03-15)
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
### Features
|
|
10
|
-
|
|
11
|
-
* add CockroachDB support with a new dialect, querier, and Docker Compose configuration, extending PostgreSQL's base implementation. ([34b94e5](https://github.com/rogerpadilla/uql/commit/34b94e5ed25fa5e68a0ab868085bb8a157990574))
|
|
12
|
-
* Add CockroachDB support with native upsert and mapped driver execution. ([2b2538e](https://github.com/rogerpadilla/uql/commit/2b2538e2d6317a4729342c794cce73e6229ab038))
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
1
|
# Changelog
|
|
19
2
|
|
|
20
3
|
All notable changes to this project will be documented in this file. Please add new changes to the top.
|
|
21
4
|
|
|
22
5
|
date format is [yyyy-mm-dd]
|
|
23
6
|
|
|
24
|
-
## [0.
|
|
7
|
+
## [0.5.2] - 2026-03-17
|
|
8
|
+
### Testing
|
|
9
|
+
- **Suite reliability**: Ensured the full test suite runs without runtime errors across all dialects with coverage thresholds still met (>97% statements, >90% branches).
|
|
10
|
+
|
|
11
|
+
## [0.5.1] - 2026-03-15
|
|
12
|
+
### Chore
|
|
13
|
+
- **Documentation**: Unified documentation strategy using NPM lifecycle scripts across subpackages.
|
|
14
|
+
- **Maintenance**: Removed redundant `copyfiles` dependency and cleaned up build scripts.
|
|
15
|
+
- **README**: Refined technical copy and visual feedback sections for a better developer documentation experience.
|
|
16
|
+
|
|
17
|
+
## [0.5.0] - 2026-03-15
|
|
18
|
+
### Features
|
|
19
|
+
- **CockroachDB Support**: Full integration with a new dialect, querier, and Docker Compose configuration. Supports native upsert and mapped driver execution.
|
|
25
20
|
### New Features
|
|
26
21
|
- **CockroachDB Support**: Added first-class support for `cockroachdb` dialect, leveraging its PostgreSQL wire-compatibility. Includes native `upsert` support and seamlessly mapped driver execution.
|
|
27
22
|
|
package/README.md
CHANGED
|
@@ -4,11 +4,10 @@
|
|
|
4
4
|
|
|
5
5
|
[](https://github.com/rogerpadilla/uql) [](https://coveralls.io/github/rogerpadilla/uql?branch=main) [](https://github.com/rogerpadilla/uql/blob/main/LICENSE) [](https://www.npmjs.com/package/uql-orm)
|
|
6
6
|
|
|
7
|
-
**[UQL](https://uql-orm.dev)** is
|
|
8
|
-
|
|
7
|
+
**[UQL](https://uql-orm.dev)** is a clean, ultra-fast TypeScript ORM designed for developers who value portability and performance. [Measured at **3.9M+ ops/s**](https://github.com/rogerpadilla/ts-orm-benchmark), it delivers a 4x-40x overhead advantage over traditional ORMs. It eliminates the friction between SQL and MongoDB, providing a unified, type-safe experience without proprietary DSLs or heavy codegen steps.
|
|
9
8
|
|
|
10
9
|
```ts
|
|
11
|
-
const
|
|
10
|
+
const results = await querier.findMany(User, {
|
|
12
11
|
$select: { name: true, profile: { $select: { picture: true } } },
|
|
13
12
|
$where: { name: { $istartsWith: 'a' }, posts: { tags: { name: 'typescript' } } },
|
|
14
13
|
$sort: { createdAt: 'desc' },
|
|
@@ -20,22 +19,23 @@ const users = await querier.findMany(User, {
|
|
|
20
19
|
|
|
21
20
|
## Features
|
|
22
21
|
|
|
23
|
-
| Feature
|
|
24
|
-
|
|
|
25
|
-
| **[Intelligent Querying](https://uql-orm.dev/querying/relations)**
|
|
26
|
-
| **Serializable JSON**
|
|
27
|
-
| **Unified Dialects**
|
|
28
|
-
| **[Naming Strategies](https://uql-orm.dev/naming-strategy)**
|
|
29
|
-
| **Smart SQL Engine**
|
|
30
|
-
| **Thread-Safe by Design**
|
|
31
|
-
| **[Declarative Transactions](https://uql-orm.dev/querying/transactions)**
|
|
32
|
-
| **[Lifecycle Hooks](https://uql-orm.dev/entities/lifecycle-hooks)
|
|
33
|
-
| **[Aggregate Queries](https://uql-orm.dev/querying/aggregate)** | `GROUP BY`, `HAVING`,
|
|
34
|
-
| **[Semantic Search](https://uql-orm.dev/querying/semantic-search)** |
|
|
35
|
-
| **[Cursor Streaming](https://uql-orm.dev/querying/streaming)** |
|
|
36
|
-
| **[Modern & Versatile](https://uql-orm.dev/entities/virtual-fields)** |
|
|
37
|
-
| **[Database Migrations](https://www.uql-orm.dev/migrations)**
|
|
38
|
-
| **[Logging & Monitoring](https://www.uql-orm.dev/logging)**
|
|
22
|
+
| Feature | Why it matters |
|
|
23
|
+
| :--- | :--- |
|
|
24
|
+
| **[Intelligent Querying](https://uql-orm.dev/querying/relations)** | Deep auto-completion for operators and relations at any depth—no more guessing property names. |
|
|
25
|
+
| **Serializable JSON** | 100% valid JSON queries. Send your query logic over HTTP, gRPC or WebSockets as easily as a string—the only ORM with a native cross-network protocol. |
|
|
26
|
+
| **Unified Dialects** | Write once, run anywhere. Seamlessly switch between PostgreSQL, MySQL, SQLite, and MongoDB. |
|
|
27
|
+
| **[Naming Strategies](https://uql-orm.dev/naming-strategy)** | No more `camelCase` vs `snake_case` headaches. Map your code to your database automatically. |
|
|
28
|
+
| **Smart SQL Engine** | Zero-allocation SQL generation. [1st in every benchmark category](https://github.com/rogerpadilla/ts-orm-benchmark). |
|
|
29
|
+
| **Thread-Safe by Design** | Protect your data integrity with centralized task queues and the `@Serialized()` decorator. |
|
|
30
|
+
| **[Declarative Transactions](https://uql-orm.dev/querying/transactions)** | Clean `@Transactional()` decorators that work beautifully with modern DI frameworks like NestJS. |
|
|
31
|
+
| **[Lifecycle Hooks](https://uql-orm.dev/entities/lifecycle-hooks)** | Automate validation, timestamps, and computed logic with intuitive class-based decorators. |
|
|
32
|
+
| **[Aggregate Queries](https://uql-orm.dev/querying/aggregate)** | Real-time analytics with `GROUP BY`, `HAVING`, and native math operators across all dialects. |
|
|
33
|
+
| **[Semantic Search](https://uql-orm.dev/querying/semantic-search)** | Native vector similarity search. Rank results by meaning using standard ORM operators. |
|
|
34
|
+
| **[Cursor Streaming](https://uql-orm.dev/querying/streaming)** | Process millions of rows with a stable memory footprint using native driver-level cursors. |
|
|
35
|
+
| **[Modern & Versatile](https://uql-orm.dev/entities/virtual-fields)** | Pure ESM, high-res timing, built-in soft-delete, and first-class JSONB/JSON support. |
|
|
36
|
+
| **[Database Migrations](https://www.uql-orm.dev/migrations)** | Entity-First synchronization. DDL is auto-generated by diffing your code against the live DB. |
|
|
37
|
+
| **[Logging & Monitoring](https://www.uql-orm.dev/logging)** | High-visibility debugging with slow-query detection and high-contrast terminal output. |
|
|
38
|
+
| **[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. |
|
|
39
39
|
|
|
40
40
|
|
|
41
41
|
|
|
@@ -50,15 +50,16 @@ npm install uql-orm # or bun add / pnpm add
|
|
|
50
50
|
|
|
51
51
|
### Supported Drivers (pick according to your database)
|
|
52
52
|
|
|
53
|
-
| Database
|
|
54
|
-
|
|
|
55
|
-
| **PostgreSQL** (incl. Neon, Cockroach, Yugabyte) | `npm install pg`
|
|
56
|
-
| **MySQL** (incl. TiDB, Aurora)
|
|
57
|
-
| **MariaDB**
|
|
58
|
-
| **SQLite**
|
|
59
|
-
| **LibSQL** (incl. Turso)
|
|
60
|
-
| **MongoDB**
|
|
61
|
-
| **
|
|
53
|
+
| Database | Command |
|
|
54
|
+
| :--- | :--- |
|
|
55
|
+
| **PostgreSQL** (incl. Neon, Cockroach, Yugabyte) | `npm install pg` |
|
|
56
|
+
| **MySQL** (incl. TiDB, Aurora) | `npm install mysql2` |
|
|
57
|
+
| **MariaDB** | `npm install mariadb` |
|
|
58
|
+
| **SQLite** | `npm install better-sqlite3` |
|
|
59
|
+
| **LibSQL** (incl. Turso) | `npm install @libsql/client` |
|
|
60
|
+
| **MongoDB** | `npm install mongodb` |
|
|
61
|
+
| **CockroachDB** | `npm install pg` |
|
|
62
|
+
| **Cloudflare D1** | _Native (no driver needed)_ |
|
|
62
63
|
|
|
63
64
|
### TypeScript Configuration
|
|
64
65
|
|
|
@@ -75,30 +76,28 @@ Ensure your `tsconfig.json` is configured to support decorators and metadata:
|
|
|
75
76
|
|
|
76
77
|
**Note:** UQL is Modern Pure ESM — ensure your project's `module` supports ESM imports (e.g., `NodeNext`, `ESNext`, `Bundler`).
|
|
77
78
|
|
|
78
|
-
## 2. Define
|
|
79
|
+
## 2. Define your Entities
|
|
79
80
|
|
|
80
81
|
Annotate your classes with decorators. UQL's engine uses this metadata for both type-safe querying and precise DDL generation.
|
|
81
82
|
|
|
82
83
|
### Core Decorators
|
|
83
84
|
|
|
84
|
-
| Decorator
|
|
85
|
-
|
|
|
86
|
-
| `@Entity()`
|
|
87
|
-
| `@Id()`
|
|
88
|
-
| `@Field()`
|
|
89
|
-
| `@Index()`
|
|
90
|
-
| `@OneToOne`
|
|
91
|
-
| `@OneToMany`
|
|
92
|
-
| `@ManyToOne`
|
|
93
|
-
| `@ManyToMany` | Defines a many-to-many relationship.
|
|
94
|
-
| `@BeforeInsert`
|
|
95
|
-
| `@
|
|
96
|
-
| `@BeforeDelete` / `@AfterDelete` | Lifecycle hooks fired around `delete` operations. |
|
|
97
|
-
| `@AfterLoad` | Lifecycle hook fired after loading entities from the database. |
|
|
85
|
+
| Decorator | Purpose |
|
|
86
|
+
| :--- | :--- |
|
|
87
|
+
| `@Entity()` | Marks a class as a database table/collection. |
|
|
88
|
+
| `@Id()` | Defines the Primary Key with support for `onInsert` generators. |
|
|
89
|
+
| `@Field()` | Standard column. Use `{ references: ... }` for Foreign Keys. |
|
|
90
|
+
| `@Index()` | Defines a composite or custom index on one or more columns. |
|
|
91
|
+
| `@OneToOne` | Defines a one-to-one relationship. |
|
|
92
|
+
| `@OneToMany` | Defines a one-to-many relationship. |
|
|
93
|
+
| `@ManyToOne` | Defines a many-to-one relationship. |
|
|
94
|
+
| `@ManyToMany` | Defines a many-to-many relationship. |
|
|
95
|
+
| `@BeforeInsert` | Lifecycle hooks fired around database operations. |
|
|
96
|
+
| `@AfterLoad` | Lifecycle hook fired after loading entities. |
|
|
98
97
|
|
|
99
98
|
### Type Abstraction: Logical vs. Physical
|
|
100
99
|
|
|
101
|
-
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
|
|
100
|
+
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.
|
|
102
101
|
|
|
103
102
|
| Property | Purpose | Values |
|
|
104
103
|
| :--- | :--- | :--- |
|
|
@@ -226,7 +225,7 @@ export class PostTag {
|
|
|
226
225
|
}
|
|
227
226
|
```
|
|
228
227
|
|
|
229
|
-
> **
|
|
228
|
+
> **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.
|
|
230
229
|
|
|
231
230
|
|
|
232
231
|
|
|
@@ -255,7 +254,9 @@ export default {
|
|
|
255
254
|
} satisfies Config;
|
|
256
255
|
```
|
|
257
256
|
|
|
258
|
-
> **
|
|
257
|
+
> **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.
|
|
258
|
+
>
|
|
259
|
+
> **Senior Insight**: In the 2026 landscape of AI and Edge, the ability to securely proxy queries via a **First-Party Bridge** (UQL) vs. running a local DB runtime (Drizzle/PGlite) or manual API mapping (Prisma) is the difference between shipping in days or weeks.
|
|
259
260
|
|
|
260
261
|
|
|
261
262
|
|
|
@@ -268,20 +269,19 @@ UQL provides a straightforward API to interact with your data. **Always ensure q
|
|
|
268
269
|
```ts
|
|
269
270
|
const querier = await pool.getQuerier();
|
|
270
271
|
try {
|
|
271
|
-
const
|
|
272
|
+
const results = await querier.findMany(User, {
|
|
272
273
|
$select: {
|
|
273
274
|
name: true,
|
|
274
275
|
profile: { $select: { bio: true }, $required: true } // INNER JOIN
|
|
275
276
|
},
|
|
276
277
|
$where: {
|
|
277
278
|
status: 'active',
|
|
278
|
-
name: { $istartsWith: 'a' }
|
|
279
|
+
name: { $istartsWith: 'a' }
|
|
279
280
|
},
|
|
280
281
|
$limit: 10,
|
|
281
|
-
$skip: 0
|
|
282
282
|
});
|
|
283
283
|
} finally {
|
|
284
|
-
await querier.release(); //
|
|
284
|
+
await querier.release(); // Always release back to the pool
|
|
285
285
|
}
|
|
286
286
|
```
|
|
287
287
|
|
|
@@ -297,6 +297,20 @@ LIMIT 10 OFFSET 0
|
|
|
297
297
|
|
|
298
298
|
|
|
299
299
|
|
|
300
|
+
### Modern Indexing: Semantic Search
|
|
301
|
+
|
|
302
|
+
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.
|
|
303
|
+
|
|
304
|
+
```ts
|
|
305
|
+
const results = await querier.findMany(Item, {
|
|
306
|
+
$select: { id: true, title: true },
|
|
307
|
+
$sort: { $vector: { embedding: queryVector } },
|
|
308
|
+
$limit: 10,
|
|
309
|
+
});
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
|
|
300
314
|
### Advanced: Virtual Fields & Raw SQL
|
|
301
315
|
|
|
302
316
|
Define complex logic directly in your entities using `raw` functions. These are resolved during SQL generation for peak efficiency.
|
|
@@ -347,7 +361,7 @@ const posts = await querier.findMany(Post, {
|
|
|
347
361
|
|
|
348
362
|
**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))`
|
|
349
363
|
|
|
350
|
-
> **
|
|
364
|
+
> **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.
|
|
351
365
|
|
|
352
366
|
|
|
353
367
|
|
|
@@ -459,10 +473,10 @@ try {
|
|
|
459
473
|
|
|
460
474
|
## 5. Migrations & Synchronization
|
|
461
475
|
|
|
462
|
-
UQL takes an **Entity-First** approach
|
|
476
|
+
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.
|
|
463
477
|
|
|
464
478
|
```bash
|
|
465
|
-
# 1. Update your entity (add a field, change a type,
|
|
479
|
+
# 1. Update your entity (add a field, change a type, etc.)
|
|
466
480
|
# 2. Auto-generate the migration
|
|
467
481
|
npx uql-migrate generate:entities add_user_nickname
|
|
468
482
|
|
|
@@ -470,7 +484,7 @@ npx uql-migrate generate:entities add_user_nickname
|
|
|
470
484
|
npx uql-migrate up
|
|
471
485
|
```
|
|
472
486
|
|
|
473
|
-
> **Your entities are the single source of truth
|
|
487
|
+
> **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.
|
|
474
488
|
|
|
475
489
|
### 1. Unified Configuration
|
|
476
490
|
|
|
@@ -568,6 +582,8 @@ const migrator = new Migrator(pool, {
|
|
|
568
582
|
await migrator.autoSync({ logging: true });
|
|
569
583
|
```
|
|
570
584
|
|
|
585
|
+
> **Senior Insight**: In development, `autoSync` is your best friend. It keeps your schema alive as you iterate, but it’s uniquely designed to never drop columns or change types—ensuring your data remains safe while you move at light speed.
|
|
586
|
+
|
|
571
587
|
|
|
572
588
|
|
|
573
589
|
## 6. Logging & Monitoring
|
|
@@ -587,7 +603,7 @@ UQL features a professional-grade, structured logging system designed for high v
|
|
|
587
603
|
|
|
588
604
|
### Visual Feedback
|
|
589
605
|
|
|
590
|
-
The `DefaultLogger` provides high-contrast, colored output
|
|
606
|
+
The `DefaultLogger` provides high-contrast, colored output that makes debugging feel like a premium experience:
|
|
591
607
|
|
|
592
608
|
```text
|
|
593
609
|
query: SELECT * FROM "user" WHERE "id" = $1 -- [123] [2ms]
|
|
@@ -595,7 +611,7 @@ slow query: UPDATE "post" SET "title" = $1 -- ["New Title"] [1250ms]
|
|
|
595
611
|
error: Failed to connect to database: Connection timeout
|
|
596
612
|
```
|
|
597
613
|
|
|
598
|
-
> **
|
|
614
|
+
> **Senior Insight**: In production, keep your logs lean. By setting `logger: ['error', 'warn', 'slowQuery']`, UQL stays silent until a performance bottleneck actually occurs.
|
|
599
615
|
|
|
600
616
|
|
|
601
617
|
|
package/package.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"homepage": "https://uql-orm.dev",
|
|
4
4
|
"description": "Fast, type-safe TypeScript ORM — one API for every database",
|
|
5
5
|
"license": "MIT",
|
|
6
|
-
"version": "0.5.
|
|
6
|
+
"version": "0.5.3",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"sideEffects": false,
|
|
9
9
|
"main": "./dist/index.js",
|
|
@@ -44,9 +44,10 @@
|
|
|
44
44
|
"CHANGELOG.md"
|
|
45
45
|
],
|
|
46
46
|
"scripts": {
|
|
47
|
-
"
|
|
47
|
+
"prepack": "cp ../../README.md . && cp ../../CHANGELOG.md .",
|
|
48
|
+
"postpack": "rm README.md CHANGELOG.md",
|
|
48
49
|
"compile.browser": "bunchee --clean false --no-dts ./src/browser/index.ts --sourcemap -o ./dist/browser/uql-browser.min.js 2>/dev/null",
|
|
49
|
-
"build": "bun run clean && tsc -b tsconfig.build.json && bun run compile.browser
|
|
50
|
+
"build": "bun run clean && tsc -b tsconfig.build.json && bun run compile.browser",
|
|
50
51
|
"start": "tsc --watch",
|
|
51
52
|
"clean": "rimraf dist *.tsbuildinfo"
|
|
52
53
|
},
|
|
@@ -106,11 +107,10 @@
|
|
|
106
107
|
"@types/sqlstring": "^2.3.2",
|
|
107
108
|
"better-sqlite3": "^12.8.0",
|
|
108
109
|
"bunchee": "^6.9.4",
|
|
109
|
-
"copyfiles": "^2.4.1",
|
|
110
110
|
"express": "^5.2.1",
|
|
111
111
|
"mariadb": "^3.5.2",
|
|
112
112
|
"mongodb": "^7.1.0",
|
|
113
|
-
"mysql2": "^3.
|
|
113
|
+
"mysql2": "^3.20.0",
|
|
114
114
|
"pg": "^8.20.0",
|
|
115
115
|
"pg-query-stream": "^4.14.0"
|
|
116
116
|
},
|
|
@@ -154,5 +154,5 @@
|
|
|
154
154
|
"publishConfig": {
|
|
155
155
|
"access": "public"
|
|
156
156
|
},
|
|
157
|
-
"gitHead": "
|
|
157
|
+
"gitHead": "ff21d2ff14c42a68b250df3f6c77368d3f15eda7"
|
|
158
158
|
}
|