metal-orm 1.0.58 → 1.0.59

package/README.md

@@ -102,9 +102,9 @@ Full docs live in the `docs/` folder:
 - **Typed temporal columns**: `col.date()` / `col.datetime()` / `col.timestamp()` default to `string` but accept a generic when your driver returns `Date` (e.g. `col.date<Date>()`).
 - **Fluent query builder** over a real SQL AST  
   (`SelectQueryBuilder`, `InsertQueryBuilder`, `UpdateQueryBuilder`, `DeleteQueryBuilder`).
-- **Advanced SQL**: CTEs, aggregates, window functions, subqueries, bitwise operators (`&`, `|`, `^`, `<<`, `>>`), JSON, CASE, EXISTS, and the full SQL function catalog (e.g. `STDDEV`, `VARIANCE`, `LOG2`, `CBRT`, `COALESCE`, `NULLIF`, `GREATEST`, `LEAST`, `IFNULL`, `LOCALTIME`, `LOCALTIMESTAMP`, `AGE`).
-- **Table-valued functions**: use the new `tvf(key, …)` helper when you want portable intents such as `ARRAY_UNNEST`, letting the dialects’ `TableFunctionStrategy` renderers emit dialect-specific syntax (`LATERAL`/`WITH ORDINALITY`, alias validation, quoting, etc.). `fnTable()` remains available as the raw escape hatch when you need to emit a specific SQL function directly.
-- **String helpers**: `lower`, `upper`, `trim`, `ltrim/rtrim`, `concat/concatWs`, `substr/left/right`, `position/instr/locate`, `replace`, `repeat`, `lpad/rpad`, `space`, and more with dialect-aware rendering.
+- **Advanced SQL**: CTEs, aggregates, window functions, subqueries, bitwise operators (`&`, `|`, `^`, `<<`, `>>`), JSON, CASE, EXISTS, and the full SQL function catalog (e.g. `STDDEV`, `VARIANCE`, `LOG2`, `CBRT`, `COALESCE`, `NULLIF`, `GREATEST`, `LEAST`, `IFNULL`, `LOCALTIME`, `LOCALTIMESTAMP`, `AGE`).
+- **Table-valued functions**: use the new `tvf(key, …)` helper when you want portable intents such as `ARRAY_UNNEST`, letting the dialects’ `TableFunctionStrategy` renderers emit dialect-specific syntax (`LATERAL`/`WITH ORDINALITY`, alias validation, quoting, etc.). `fnTable()` remains available as the raw escape hatch when you need to emit a specific SQL function directly.
+- **String helpers**: `lower`, `upper`, `trim`, `ltrim/rtrim`, `concat/concatWs`, `substr/left/right`, `position/instr/locate`, `replace`, `repeat`, `lpad/rpad`, `space`, and more with dialect-aware rendering.
 - **Set operations**: `union`, `unionAll`, `intersect`, `except` across all dialects (ORDER/LIMIT apply to the combined result; hydration is disabled for compound queries so rows are returned as-is without collapsing duplicates).
 - **Expression builders**: `eq`, `and`, `or`, `between`, `inList`, `exists`, `jsonPath`, `caseWhen`, window functions like `rowNumber`, `rank`, `lag`, `lead`, etc., all backed by typed AST nodes.
 - **Relation-aware hydration**: turn flat rows into nested objects (`user.posts`, `user.roles`, etc.) using a hydration plan derived from the AST metadata.
@@ -231,10 +231,10 @@ todos.columns.done.default = false;
 const t = tableRef(todos);
 
 // 2) Build a simple query
-const listOpenTodos = selectFrom(todos)
-  .select('id', 'title', 'done')
-  .where(eq(t.done, false))
-  .orderBy(t.id, 'ASC');
+const listOpenTodos = selectFrom(todos)
+  .select('id', 'title', 'done')
+  .where(eq(t.done, false))
+  .orderBy(t.id, 'ASC');
 
 // 3) Compile to SQL + params
 const dialect = new MySqlDialect();
@@ -244,21 +244,21 @@ const { sql, params } = listOpenTodos.compile(dialect);
 const connection = await mysql.createConnection({ /* ... */ });
 const [rows] = await connection.execute(sql, params);
 
-console.log(rows);
-// [
-//   { id: 1, title: 'Write docs', done: 0 },
-//   { id: 2, title: 'Ship feature', done: 0 },
-// ]
-```
-
-If you keep a reusable array of column names (e.g. shared across helpers or pulled from config), you can spread it into `.select(...)` since the method accepts rest arguments:
-
-```ts
-const defaultColumns = ['id', 'title', 'done'] as const;
-const listOpenTodos = selectFrom(todos).select(...defaultColumns);
-```
-
-That's it: schema, query, SQL, done.
+console.log(rows);
+// [
+//   { id: 1, title: 'Write docs', done: 0 },
+//   { id: 2, title: 'Ship feature', done: 0 },
+// ]
+```
+
+If you keep a reusable array of column names (e.g. shared across helpers or pulled from config), you can spread it into `.select(...)` since the method accepts rest arguments:
+
+```ts
+const defaultColumns = ['id', 'title', 'done'] as const;
+const listOpenTodos = selectFrom(todos).select(...defaultColumns);
+```
+
+That's it: schema, query, SQL, done.
 
 If you are using the Level 2 runtime (`OrmSession`), `SelectQueryBuilder` also provides `count(session)` and `executePaged(session, { page, pageSize })` for common pagination patterns.
 
@@ -275,7 +275,7 @@ const listOpenTodos = selectFrom(todos)
   .orderBy(t.id, 'ASC');
 ```
 
-`select`, `include` (with `columns`), `includePick`, `selectColumnsDeep`, the `sel()` helpers for tables, and `esel()` for entities all build typed selection maps without repeating `table.columns.*`. Use those helpers when building query selections and reserve `table.columns.*` for schema definition, relations, or rare cases where you need a column reference outside of a picker. See the [Query Builder docs](./docs/query-builder.md#selection-helpers) for the reference, examples, and best practices for these helpers.
+`select`, `include` (with `columns`), `includePick`, `selectColumnsDeep`, the `sel()` helpers for tables, and `esel()` for entities all build typed selection maps without repeating `table.columns.*`. Use those helpers when building query selections and reserve `table.columns.*` for schema definition, relations, or rare cases where you need a column reference outside of a picker. See the [Query Builder docs](./docs/query-builder.md#selection-helpers) for the reference, examples, and best practices for these helpers.
 
 #### Ergonomic column access (opt-in) with `tableRef`
 
@@ -459,17 +459,20 @@ What the runtime gives you:
 - Relation tracking (add/remove/sync on collections).
 - Cascades on relations: `'all' | 'persist' | 'remove' | 'link'`.
 - Single flush: `session.commit()` figures out inserts, updates, deletes, and pivot changes.
-- Column pickers to stay DRY: `select` on the root table, `include` (with `columns`) or `includePick` on relations, and `selectColumnsDeep` or the `sel`/`esel` helpers to build typed selection maps without repeating `table.columns.*`.
+- Column pickers to stay DRY: `select` on the root table, `include` (with `columns`) or `includePick` on relations, and `selectColumnsDeep` or the `sel`/`esel` helpers to build typed selection maps without repeating `table.columns.*`.
+- Tip: if you assign relations after `defineTable`, use `setRelations(table, { ... })` so TypeScript can validate `include(..., { columns: [...] })` and pivot columns. See `docs/query-builder.md`.
 
 <a id="level-3"></a>
 ### Level 3: Decorator entities ✨
 
-Finally, you can describe your models with decorators and still use the same runtime and query builder.
-
-```ts
-import mysql from 'mysql2/promise';
-import {
-  Orm,
+Finally, you can describe your models with decorators and still use the same runtime and query builder.
+
+The decorator layer is built on the TC39 Stage 3 standard (TypeScript 5.6+), so you simply decorate class fields (or accessors if you need custom logic) and the standard `ClassFieldDecoratorContext` keeps a metadata bag on `context.metadata`/`Symbol.metadata`. `@Entity` reads that bag when it runs and builds your `TableDef`s—no `experimentalDecorators`, parameter decorators, or extra polyfills required.
+
+```ts
+import mysql from 'mysql2/promise';
+import {
+  Orm,
   OrmSession,
   MySqlDialect,
   col,
@@ -550,7 +553,7 @@ user.posts.add({ title: 'From decorators' });
 await session.commit();
 ```
 
-Tip: to keep selections terse, use `select`, `include` (with `columns`), or the `sel`/`esel` helpers instead of spelling `table.columns.*` over and over.
+Tip: to keep selections terse, use `select`, `include` (with `columns`), or the `sel`/`esel` helpers instead of spelling `table.columns.*` over and over.
 
 This level is nice when: