uql-orm 0.106.1 → 0.107.1
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/README.md +2 -2
- package/dist/browser/uql-browser.min.js.map +1 -1
- package/dist/dialect/abstractSqlDialect.js +3 -3
- package/dist/entity/decorator/bag.d.ts +1 -1
- package/dist/entity/metadata/{schemaFixture → definedFixture}/animal.d.ts +2 -2
- package/dist/entity/metadata/{schemaFixture → definedFixture}/author.d.ts +2 -2
- package/dist/entity/metadata/{schemaFixture → definedFixture}/book.d.ts +4 -4
- package/dist/entity/metadata/definition.d.ts +18 -8
- package/dist/entity/metadata/definition.js +59 -38
- package/dist/migrate/codegen/fieldOptionsSource.js +8 -1
- package/dist/mongodb/mongoDialect.d.ts +0 -1
- package/dist/mongodb/mongoDialect.js +4 -7
- package/dist/mssql/mssqlDialect.js +5 -5
- package/dist/querier/abstractSqlQuerier.js +3 -3
- package/dist/schema/declaredColumn.d.ts +1 -1
- package/dist/schema/declaredColumn.js +1 -1
- package/dist/schema/schemaASTBuilder.js +3 -3
- package/dist/sqlite/sqliteQuerier.d.ts +1 -1
- package/dist/type/column.d.ts +3 -3
- package/dist/type/{schemaEntity.d.ts → definedEntity.d.ts} +45 -45
- package/dist/type/entity.d.ts +9 -7
- package/dist/type/index.d.ts +1 -1
- package/dist/type/index.js +1 -1
- package/dist/type/query.d.ts +1 -1
- package/dist/util/field.util.d.ts +4 -6
- package/dist/util/field.util.js +5 -9
- package/package.json +7 -7
- package/skills/uql-orm/SKILL.md +42 -6
- /package/dist/entity/metadata/{schemaFixture → definedFixture}/animal.js +0 -0
- /package/dist/entity/metadata/{schemaFixture → definedFixture}/author.js +0 -0
- /package/dist/entity/metadata/{schemaFixture → definedFixture}/book.js +0 -0
- /package/dist/type/{schemaEntity.js → definedEntity.js} +0 -0
package/skills/uql-orm/SKILL.md
CHANGED
|
@@ -10,7 +10,7 @@ description: >
|
|
|
10
10
|
|
|
11
11
|
# UQL
|
|
12
12
|
|
|
13
|
-
An entity is a decorated class, or
|
|
13
|
+
An entity is a decorated class, or declared as data with `defineEntity`, its row type derived. A query is a JSON object checked key by key against the entity, and it runs the same on every supported database. There is no schema file, no generated client and no query builder.
|
|
14
14
|
|
|
15
15
|
Full docs are Markdown: the index at https://uql-orm.dev/llms.txt, and each page at its URL plus `.md`. Read the page for the task before guessing an option.
|
|
16
16
|
|
|
@@ -22,7 +22,7 @@ npm install uql-orm pg # or mysql2, mariadb, better-sqlite3, mongodb, @libsql/
|
|
|
22
22
|
|
|
23
23
|
ESM only. Needs Node 22.18+, Bun or an edge runtime, and TypeScript 5.7+.
|
|
24
24
|
|
|
25
|
-
Decorators are TC39 standard. Never enable `experimentalDecorators` or `emitDecoratorMetadata`, and never import `reflect-metadata`. A project on legacy decorators (NestJS, Angular) keeps its config and defines entities with `defineEntity`: https://uql-orm.dev/entities/
|
|
25
|
+
Decorators are TC39 standard. Never enable `experimentalDecorators` or `emitDecoratorMetadata`, and never import `reflect-metadata`. A project on legacy decorators (NestJS, Angular) keeps its config and defines entities with `defineEntity`: https://uql-orm.dev/entities/define-entity.md
|
|
26
26
|
|
|
27
27
|
Node runs no decorators natively yet, so add `tsx` there (`npm i -D tsx`); `uql-migrate` loads `uql.config.ts` through it. A bundler that minifies class names needs `@Entity({ name: 'todo' })`, since the table name defaults to the class name.
|
|
28
28
|
|
|
@@ -79,10 +79,11 @@ export class Post {
|
|
|
79
79
|
|
|
80
80
|
- A column is a builder: `f.string()`, `f.text()`, `f.uuid()`, `f.number()`, `f.bigint()`, `f.decimal()`, `f.decimal(precision)`, `f.decimal(precision, scale)`, `f.boolean()`, `f.date()`, `f.json(schema?)`, `f.jsonb(schema?)`, `f.vector(dimensions)`, `f.enum(values)`, `f.version()`, `f.column(type)` for any other column type, and `f.references(() => Target)` for a foreign key, which takes the target's key type. Only the methods a column's type takes exist: `.length()` is a string's, `.precision()` a number's or a date's. A bound holds in either order around `.columnType('char')`, but not around a `sql` type, which carries its own.
|
|
81
81
|
- A column is NOT NULL unless `.nullable()`; its property then admits `null` (`title?: string | null`).
|
|
82
|
+
- A JSON column's property is `Json<T>`, where `T` is the payload: `settings?: Json<{ theme?: string }> | null`, or `Json<z.infer<typeof Settings>>` for a schema. A plain object type reads as a relation, and `$where`, `$sort` and the update operators refuse it.
|
|
82
83
|
- Declare a NOT NULL column with `!` (`email!: string`). Declare `?` for anything else an insert may omit: nullable columns, `.eager(false)` fields, and relations. A computed field is present on a default read, so it is not optional. uql fills a single-column key and a version.
|
|
83
84
|
- A NOT NULL field a default fills (`.default()`, `.onInsert()`) is `!` and listed in the class's `[filledKey]?: 'stock' | 'createdAt'`: inserts may omit it, reads always have it.
|
|
84
85
|
- `.default()` takes a value of the field's type, or SQL the database evaluates per row: `currentTimestamp`, `currentDate`, `currentTime`, `uuid` (not SQLite), `uuidv7` (Postgres 18+, MariaDB 11.7+), or ``sql`...` ``. A plain string is always text, `'CURRENT_TIMESTAMP'` included.
|
|
85
|
-
- A class inherits its base's fields, relations, hooks, filters, indexes, checks and triggers. A base of fields alone needs no `@Entity()`; one declaring indexes, filters, checks or triggers but no table is `@Entity({ abstract: true, ... }) abstract class`, or
|
|
86
|
+
- A class inherits its base's fields, relations, hooks, filters, indexes, checks and triggers. A base of fields alone needs no `@Entity()`; one declaring indexes, filters, checks or triggers but no table is `@Entity({ abstract: true, ... }) abstract class`, or `abstract: true` in `defineEntity`. A query or write on one does not compile: query the entities extending it.
|
|
86
87
|
- `Date` is an instant, stored in UTC to the millisecond on every engine. `f.decimal()` is exact text (`price?: string | null`). `f.number().precision(10).scale(2)` opts into a rounding JS number.
|
|
87
88
|
- Members are named by callbacks, never strings: `mappedBy: (post) => post.author`, `references: (post) => post.authorId`. Either may be left out where only one member fits: a decorated many-to-one's one foreign key to its target, a one-to-many's one many-to-one pointing back.
|
|
88
89
|
- `@ManyToMany({ entity: () => Tag, through: () => PostTag })` names the junction entity. `cascade: true` writes related rows in the same transaction; an update replaces a to-many's rows.
|
|
@@ -93,7 +94,40 @@ export class Post {
|
|
|
93
94
|
- JSON path index: read the path off the column's ref, `index([user.settings.theme])` for text, `index([{ column: user.settings.rating, type: Number }])` for any other value, `type: [String]` for an array's elements. MySQL keys a text path or element as `CHAR(n)`, `{ column: user.tags, type: [String], charLength: 64 }`, and a `TEXT` column by a prefix, `{ column: post.body, prefixLength: 64 }`.
|
|
94
95
|
- Triggers run in the database: `@Entity({ triggers: (post, trigger) => [trigger({ on: 'afterUpdate', of: [post.status], run })] })`, where `run` returns a body built from `insertInto`, `upsertInto`, `updateTable`, `deleteFrom` and `refuse(message)`. A trigger's writes skip uql's fills and entity filters. MongoDB has no triggers: https://uql-orm.dev/entities/triggers.md
|
|
95
96
|
|
|
96
|
-
###
|
|
97
|
+
### Choosing a form
|
|
98
|
+
|
|
99
|
+
Both forms are supported, mix them per entity, and produce the same queries and types.
|
|
100
|
+
|
|
101
|
+
- Decorators
|
|
102
|
+
- Pros
|
|
103
|
+
- A named class type shows on hover.
|
|
104
|
+
- A column can be a foreign key (`@Field(f.references(() => User))`), so entities may reference each other in any order.
|
|
105
|
+
- No `.relations()` ordering rules.
|
|
106
|
+
- Shared structure through base classes (`StampedEntity`, `WorkspaceScoped`) that carry fields and relations.
|
|
107
|
+
- The familiar form from TypeORM and MikroORM.
|
|
108
|
+
- Cons
|
|
109
|
+
- Each field is written twice, as a builder and as a TypeScript property (`@Field(f.string()) name!: string`).
|
|
110
|
+
- The TC39 decorator transform is required: Node needs `tsx`, and some bundlers need a Babel step.
|
|
111
|
+
- Without `@Entity({ name })`, the table name comes from the class name, which a minifier can change.
|
|
112
|
+
- Higher type-check cost on the benchmark model (9,297 vs 5,110 instantiations).
|
|
113
|
+
- Cannot be declared at run time.
|
|
114
|
+
- `uql-codemod` cannot convert it into `defineEntity`.
|
|
115
|
+
- `defineEntity`
|
|
116
|
+
- Pros
|
|
117
|
+
- The row type is derived from the builders, with nothing written twice.
|
|
118
|
+
- Shorter: 19 to 30% fewer lines in the two apps this was measured on.
|
|
119
|
+
- Lower type-check cost on the benchmark model.
|
|
120
|
+
- Shared relation helpers, and derived fields declared with their relations.
|
|
121
|
+
- Plain data: no transform, and it can be built at run time (a CMS content type).
|
|
122
|
+
- The form for projects that cannot enable TC39 decorators, such as legacy-decorator NestJS and Angular.
|
|
123
|
+
- Cons
|
|
124
|
+
- Relations are thunks declared after the columns, and `.relations()` comes last (only `.filters()` may follow it).
|
|
125
|
+
- No column-level foreign keys: a shared key is a relation helper, and an eager read across two entities can create an inference cycle (TS7022).
|
|
126
|
+
- Each entity needs a `type X = InstanceType<typeof X>` alias for its name.
|
|
127
|
+
- No class to annotate or extend: inheritance uses `extends` naming the base.
|
|
128
|
+
- Newer and less used.
|
|
129
|
+
|
|
130
|
+
### defineEntity
|
|
97
131
|
|
|
98
132
|
The same entities declared as data, the row type derived:
|
|
99
133
|
|
|
@@ -146,8 +180,8 @@ export const Book = defineEntity({
|
|
|
146
180
|
```
|
|
147
181
|
|
|
148
182
|
- Each field is a column builder, as in the decorated form. The row follows from them: a key, a version and a NOT NULL column are always present, a `.nullable()` one reads `| null`; a default (`.default()`, `.onInsert()`, `.autoIncrement()`) makes it optional on insert; `f.enum()` gives the literal union. No `!`, `?` or brands to write.
|
|
149
|
-
- The other options are sections chained after `defineEntity`, each called at most once: `computed`, `indexes`, `checks`, `triggers`, `filters` and `hooks` read the columns; `relations` comes last, but for a `filters` that reads through them: `.relations(...).filters({ byActiveAuthor: { where: { author: { active: true } } } })`. `defineEntity` itself takes `name` (the class name, which a naming strategy derives the table from), `table`, `schema`, `extends` and `fields`.
|
|
150
|
-
- Each relation is a thunk, `author: () => rel.manyToOne(...)`, so entities pointing at each other can sit in either order and in different files.
|
|
183
|
+
- The other options are sections chained after `defineEntity`, each called at most once: `computed`, `indexes`, `checks`, `triggers`, `filters` and `hooks` read the columns; `relations` comes last, but for a `filters` that reads through them: `.relations(...).filters({ byActiveAuthor: { where: { author: { active: true } } } })`. `defineEntity` itself takes `name` (the class name, which a naming strategy derives the table from), `table`, `schema`, `extends`, `abstract` and `fields`.
|
|
184
|
+
- Each relation is a thunk, `author: () => rel.manyToOne(...)`, so entities pointing at each other can sit in either order and in different files. In `defineEntity`, a foreign key is a relation: `manyToOne` names its `references` column, whose type is checked against the target's key; the column itself stays a plain field. `oneToMany(Book)` with no options is mapped by the one relation of `Book` pointing back.
|
|
151
185
|
- `relations`' second callback declares the derived fields: each value is a thunk, read lazily, of an aggregate over a to-many (`() => author.books.count()`) or a column expression. The callback's refs are the entity's own columns and its relations, so one expression can combine them.
|
|
152
186
|
- A hook is a function of the row and `{ querier, onCommit }`.
|
|
153
187
|
- A JSON column's payload is a Standard Schema, `f.json(schema)`, typed by its output: any library's schema (Zod, Valibot, ArkType), or a hand-written `StandardSchemaV1`. Without one, any path reads. The schema types the column; uql never runs it, so a write is not validated.
|
|
@@ -232,6 +266,8 @@ A `findManyStream` holds its querier until the loop ends, and other statements o
|
|
|
232
266
|
|
|
233
267
|
## Migrations
|
|
234
268
|
|
|
269
|
+
Upgrading an existing project: `npx uql-codemod --dry-run`, then `npx uql-codemod`, which rewrites what it can and reports the rest. What changed by version: https://uql-orm.dev/upgrade-guide.md
|
|
270
|
+
|
|
235
271
|
`npx uql-migrate` reads `uql.config.ts` (`bun --bun uql-migrate` on Bun):
|
|
236
272
|
|
|
237
273
|
- `sync`: applies what the entities imply. Development only.
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|