metal-orm 1.0.56 → 1.0.58

package/README.md

@@ -74,21 +74,21 @@ MetalORM is a TypeScript-first, AST-driven SQL toolkit you can dial up or down d
 <a id="documentation"></a>
 ## Documentation 📚
 
-Full docs live in the `docs/` folder:
-
-- [Introduction](https://github.com/celsowm/metal-orm/blob/main/docs/index.md)
-- [Getting Started](https://github.com/celsowm/metal-orm/blob/main/docs/getting-started.md)
-- [Level 3 Backend Tutorial](https://github.com/celsowm/metal-orm/blob/main/docs/level-3-backend-tutorial.md)
-- [Schema Definition](https://github.com/celsowm/metal-orm/blob/main/docs/schema-definition.md)
-- [Query Builder](https://github.com/celsowm/metal-orm/blob/main/docs/query-builder.md)
-- [DML Operations](https://github.com/celsowm/metal-orm/blob/main/docs/dml-operations.md)
-- [Hydration & Entities](https://github.com/celsowm/metal-orm/blob/main/docs/hydration.md)
-- [Runtime & Unit of Work](https://github.com/celsowm/metal-orm/blob/main/docs/runtime.md)
-- [Save Graph](https://github.com/celsowm/metal-orm/blob/main/docs/save-graph.md)
-- [Advanced Features](https://github.com/celsowm/metal-orm/blob/main/docs/advanced-features.md)
-- [Multi-Dialect Support](https://github.com/celsowm/metal-orm/blob/main/docs/multi-dialect-support.md)
-- [Schema Generation (DDL)](https://github.com/celsowm/metal-orm/blob/main/docs/schema-generation.md)
-- [API Reference](https://github.com/celsowm/metal-orm/blob/main/docs/api-reference.md)
+Full docs live in the `docs/` folder:
+
+- [Introduction](https://github.com/celsowm/metal-orm/blob/main/docs/index.md)
+- [Getting Started](https://github.com/celsowm/metal-orm/blob/main/docs/getting-started.md)
+- [Level 3 Backend Tutorial](https://github.com/celsowm/metal-orm/blob/main/docs/level-3-backend-tutorial.md)
+- [Schema Definition](https://github.com/celsowm/metal-orm/blob/main/docs/schema-definition.md)
+- [Query Builder](https://github.com/celsowm/metal-orm/blob/main/docs/query-builder.md)
+- [DML Operations](https://github.com/celsowm/metal-orm/blob/main/docs/dml-operations.md)
+- [Hydration & Entities](https://github.com/celsowm/metal-orm/blob/main/docs/hydration.md)
+- [Runtime & Unit of Work](https://github.com/celsowm/metal-orm/blob/main/docs/runtime.md)
+- [Save Graph](https://github.com/celsowm/metal-orm/blob/main/docs/save-graph.md)
+- [Advanced Features](https://github.com/celsowm/metal-orm/blob/main/docs/advanced-features.md)
+- [Multi-Dialect Support](https://github.com/celsowm/metal-orm/blob/main/docs/multi-dialect-support.md)
+- [Schema Generation (DDL)](https://github.com/celsowm/metal-orm/blob/main/docs/schema-generation.md)
+- [API Reference](https://github.com/celsowm/metal-orm/blob/main/docs/api-reference.md)
 - [DB ➜ TS Type Mapping](https://github.com/celsowm/metal-orm/blob/main/docs/db-to-ts-types.md)
 
 ---
@@ -102,8 +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, JSON, CASE, EXISTS.
-- **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.
@@ -230,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();
@@ -243,16 +244,23 @@ 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 },
-// ]
-```
-
-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 are using the Level 2 runtime (`OrmSession`), `SelectQueryBuilder` also provides `count(session)` and `executePaged(session, { page, pageSize })` for common pagination patterns.
+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.
 
 #### Column pickers (preferred selection helpers)
 
@@ -267,7 +275,7 @@ const listOpenTodos = selectFrom(todos)
   .orderBy(t.id, 'ASC');
 ```
 
-`select`, `selectRelationColumns`, `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`
 
@@ -451,7 +459,7 @@ 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, `selectRelationColumns` / `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.*`.
 
 <a id="level-3"></a>
 ### Level 3: Decorator entities ✨
@@ -542,7 +550,7 @@ user.posts.add({ title: 'From decorators' });
 await session.commit();
 ```
 
-Tip: to keep selections terse, use `select`/`selectRelationColumns` 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: