uql-orm 0.5.0 → 0.5.2
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 +9 -18
- package/README.md +53 -56
- package/package.json +5 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,27 +1,18 @@
|
|
|
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.1] - 2026-03-15
|
|
8
|
+
### Chore
|
|
9
|
+
- **Documentation**: Unified documentation strategy using NPM lifecycle scripts across subpackages.
|
|
10
|
+
- **Maintenance**: Removed redundant `copyfiles` dependency and cleaned up build scripts.
|
|
11
|
+
- **README**: Refined technical copy and visual feedback sections for a better developer documentation experience.
|
|
12
|
+
|
|
13
|
+
## [0.5.0] - 2026-03-15
|
|
14
|
+
### Features
|
|
15
|
+
- **CockroachDB Support**: Full integration with a new dialect, querier, and Docker Compose configuration. Supports native upsert and mapped driver execution.
|
|
25
16
|
### New Features
|
|
26
17
|
- **CockroachDB Support**: Added first-class support for `cockroachdb` dialect, leveraging its PostgreSQL wire-compatibility. Includes native `upsert` support and seamlessly mapped driver execution.
|
|
27
18
|
|
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. 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,22 @@ 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 or WebSockets as easily as a string. |
|
|
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. Built for high-throughput apps where every millisecond counts. |
|
|
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. |
|
|
39
38
|
|
|
40
39
|
|
|
41
40
|
|
|
@@ -50,15 +49,16 @@ npm install uql-orm # or bun add / pnpm add
|
|
|
50
49
|
|
|
51
50
|
### Supported Drivers (pick according to your database)
|
|
52
51
|
|
|
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
|
-
| **
|
|
52
|
+
| Database | Command |
|
|
53
|
+
| :--- | :--- |
|
|
54
|
+
| **PostgreSQL** (incl. Neon, Cockroach, Yugabyte) | `npm install pg` |
|
|
55
|
+
| **MySQL** (incl. TiDB, Aurora) | `npm install mysql2` |
|
|
56
|
+
| **MariaDB** | `npm install mariadb` |
|
|
57
|
+
| **SQLite** | `npm install better-sqlite3` |
|
|
58
|
+
| **LibSQL** (incl. Turso) | `npm install @libsql/client` |
|
|
59
|
+
| **MongoDB** | `npm install mongodb` |
|
|
60
|
+
| **CockroachDB** | `npm install pg` |
|
|
61
|
+
| **Cloudflare D1** | _Native (no driver needed)_ |
|
|
62
62
|
|
|
63
63
|
### TypeScript Configuration
|
|
64
64
|
|
|
@@ -75,30 +75,28 @@ Ensure your `tsconfig.json` is configured to support decorators and metadata:
|
|
|
75
75
|
|
|
76
76
|
**Note:** UQL is Modern Pure ESM — ensure your project's `module` supports ESM imports (e.g., `NodeNext`, `ESNext`, `Bundler`).
|
|
77
77
|
|
|
78
|
-
## 2. Define
|
|
78
|
+
## 2. Define your Entities
|
|
79
79
|
|
|
80
80
|
Annotate your classes with decorators. UQL's engine uses this metadata for both type-safe querying and precise DDL generation.
|
|
81
81
|
|
|
82
82
|
### Core Decorators
|
|
83
83
|
|
|
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. |
|
|
84
|
+
| Decorator | Purpose |
|
|
85
|
+
| :--- | :--- |
|
|
86
|
+
| `@Entity()` | Marks a class as a database table/collection. |
|
|
87
|
+
| `@Id()` | Defines the Primary Key with support for `onInsert` generators. |
|
|
88
|
+
| `@Field()` | Standard column. Use `{ references: ... }` for Foreign Keys. |
|
|
89
|
+
| `@Index()` | Defines a composite or custom index on one or more columns. |
|
|
90
|
+
| `@OneToOne` | Defines a one-to-one relationship. |
|
|
91
|
+
| `@OneToMany` | Defines a one-to-many relationship. |
|
|
92
|
+
| `@ManyToOne` | Defines a many-to-one relationship. |
|
|
93
|
+
| `@ManyToMany` | Defines a many-to-many relationship. |
|
|
94
|
+
| `@BeforeInsert` | Lifecycle hooks fired around database operations. |
|
|
95
|
+
| `@AfterLoad` | Lifecycle hook fired after loading entities. |
|
|
98
96
|
|
|
99
97
|
### Type Abstraction: Logical vs. Physical
|
|
100
98
|
|
|
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
|
|
99
|
+
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
100
|
|
|
103
101
|
| Property | Purpose | Values |
|
|
104
102
|
| :--- | :--- | :--- |
|
|
@@ -226,7 +224,7 @@ export class PostTag {
|
|
|
226
224
|
}
|
|
227
225
|
```
|
|
228
226
|
|
|
229
|
-
> **
|
|
227
|
+
> **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
228
|
|
|
231
229
|
|
|
232
230
|
|
|
@@ -255,7 +253,7 @@ export default {
|
|
|
255
253
|
} satisfies Config;
|
|
256
254
|
```
|
|
257
255
|
|
|
258
|
-
> **
|
|
256
|
+
> **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.
|
|
259
257
|
|
|
260
258
|
|
|
261
259
|
|
|
@@ -268,20 +266,19 @@ UQL provides a straightforward API to interact with your data. **Always ensure q
|
|
|
268
266
|
```ts
|
|
269
267
|
const querier = await pool.getQuerier();
|
|
270
268
|
try {
|
|
271
|
-
const
|
|
269
|
+
const results = await querier.findMany(User, {
|
|
272
270
|
$select: {
|
|
273
271
|
name: true,
|
|
274
272
|
profile: { $select: { bio: true }, $required: true } // INNER JOIN
|
|
275
273
|
},
|
|
276
274
|
$where: {
|
|
277
275
|
status: 'active',
|
|
278
|
-
name: { $istartsWith: 'a' }
|
|
276
|
+
name: { $istartsWith: 'a' }
|
|
279
277
|
},
|
|
280
278
|
$limit: 10,
|
|
281
|
-
$skip: 0
|
|
282
279
|
});
|
|
283
280
|
} finally {
|
|
284
|
-
await querier.release(); //
|
|
281
|
+
await querier.release(); // Always release back to the pool
|
|
285
282
|
}
|
|
286
283
|
```
|
|
287
284
|
|
|
@@ -347,7 +344,7 @@ const posts = await querier.findMany(Post, {
|
|
|
347
344
|
|
|
348
345
|
**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
346
|
|
|
350
|
-
> **
|
|
347
|
+
> **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
348
|
|
|
352
349
|
|
|
353
350
|
|
|
@@ -459,10 +456,10 @@ try {
|
|
|
459
456
|
|
|
460
457
|
## 5. Migrations & Synchronization
|
|
461
458
|
|
|
462
|
-
UQL takes an **Entity-First** approach
|
|
459
|
+
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
460
|
|
|
464
461
|
```bash
|
|
465
|
-
# 1. Update your entity (add a field, change a type,
|
|
462
|
+
# 1. Update your entity (add a field, change a type, etc.)
|
|
466
463
|
# 2. Auto-generate the migration
|
|
467
464
|
npx uql-migrate generate:entities add_user_nickname
|
|
468
465
|
|
|
@@ -470,7 +467,7 @@ npx uql-migrate generate:entities add_user_nickname
|
|
|
470
467
|
npx uql-migrate up
|
|
471
468
|
```
|
|
472
469
|
|
|
473
|
-
> **Your entities are the single source of truth
|
|
470
|
+
> **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
471
|
|
|
475
472
|
### 1. Unified Configuration
|
|
476
473
|
|
|
@@ -587,7 +584,7 @@ UQL features a professional-grade, structured logging system designed for high v
|
|
|
587
584
|
|
|
588
585
|
### Visual Feedback
|
|
589
586
|
|
|
590
|
-
The `DefaultLogger` provides high-contrast, colored output
|
|
587
|
+
The `DefaultLogger` provides high-contrast, colored output that makes debugging feel like a premium experience:
|
|
591
588
|
|
|
592
589
|
```text
|
|
593
590
|
query: SELECT * FROM "user" WHERE "id" = $1 -- [123] [2ms]
|
|
@@ -595,7 +592,7 @@ slow query: UPDATE "post" SET "title" = $1 -- ["New Title"] [1250ms]
|
|
|
595
592
|
error: Failed to connect to database: Connection timeout
|
|
596
593
|
```
|
|
597
594
|
|
|
598
|
-
> **
|
|
595
|
+
> **Senior Insight**: In production, keep your logs lean. By setting `logger: ['error', 'warn', 'slowQuery']`, UQL stays silent until a performance bottleneck actually occurs.
|
|
599
596
|
|
|
600
597
|
|
|
601
598
|
|
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.2",
|
|
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,7 +107,6 @@
|
|
|
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",
|
|
@@ -154,5 +154,5 @@
|
|
|
154
154
|
"publishConfig": {
|
|
155
155
|
"access": "public"
|
|
156
156
|
},
|
|
157
|
-
"gitHead": "
|
|
157
|
+
"gitHead": "ea2665cc5ef8f78f4f39d21ed456f8c59a06361e"
|
|
158
158
|
}
|