metal-orm 1.0.14 → 1.0.15

package/README.md

@@ -63,6 +63,7 @@ Full docs live in the `docs/` folder:
 - **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.
 - **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.
@@ -102,9 +103,10 @@ If you like explicit model classes, you can add a thin decorator layer on top of
 - `@Column(...)` and `@PrimaryKey(...)` on properties; decorators collect column metadata and later build `TableDef`s from it.
 - Relation decorators:
   - `@HasMany({ target, foreignKey, ... })`
+  - `@HasOne({ target, foreignKey, ... })`
   - `@BelongsTo({ target, foreignKey, ... })`
   - `@BelongsToMany({ target, pivotTable, ... })`
-- `bootstrapEntities()` scans metadata, builds `TableDef`s, wires relations with the same `hasMany` / `belongsTo` / `belongsToMany` helpers you would use manually, and returns the resulting tables.
+- `bootstrapEntities()` scans metadata, builds `TableDef`s, wires relations with the same `hasOne` / `hasMany` / `belongsTo` / `belongsToMany` helpers you would use manually, and returns the resulting tables.
 - `selectFromEntity(MyEntity)` lets you start a `SelectQueryBuilder` directly from the class.
 
 You don’t have to use decorators, but when you do, you’re still on the same AST + dialect + runtime foundation.
@@ -171,10 +173,13 @@ import {
 
 // 1) A very small table
 const todos = defineTable('todos', {
-  id: col.int().primaryKey(),
-  title: col.varchar(255).notNull(),
-  done: col.boolean().default(false),
+  id: col.primaryKey(col.int()),
+  title: col.varchar(255),
+  done: col.boolean(),
 });
+// Add constraints
+todos.columns.title.notNull = true;
+todos.columns.done.default = false;
 
 // 2) Build a simple query
 const listOpenTodos = new SelectQueryBuilder(todos)
@@ -220,20 +225,29 @@ import {
 } from 'metal-orm';
 
 const posts = defineTable('posts', {
-  id: col.int().primaryKey(),
-  title: col.varchar(255).notNull(),
-  userId: col.int().notNull(),
-  createdAt: col.timestamp().default('CURRENT_TIMESTAMP'),
+  id: col.primaryKey(col.int()),
+  title: col.varchar(255),
+  userId: col.int(),
+  createdAt: col.timestamp(),
 });
 
+// Add constraints
+posts.columns.title.notNull = true;
+posts.columns.userId.notNull = true;
+
 const users = defineTable('users', {
-  id: col.int().primaryKey(),
-  name: col.varchar(255).notNull(),
-  email: col.varchar(255).unique(),
-}, {
-  posts: hasMany(posts, 'userId'),
+  id: col.primaryKey(col.int()),
+  name: col.varchar(255),
+  email: col.varchar(255),
 });
 
+// Add relations and constraints
+users.relations = {
+  posts: hasMany(posts, 'userId'),
+};
+users.columns.name.notNull = true;
+users.columns.email.unique = true;
+
 // Build a query with relation & window function
 const builder = new SelectQueryBuilder(users)
   .select({
@@ -287,36 +301,23 @@ When you're ready, you can let MetalORM manage entities and relations for you.
 Instead of “naked objects”, your queries can return entities attached to an `OrmContext`:
 
 ```ts
+import mysql from 'mysql2/promise';
 import {
   OrmContext,
   MySqlDialect,
   SelectQueryBuilder,
   eq,
+  createMysqlExecutor,
 } from 'metal-orm';
 
 // 1) Create an OrmContext for this request
+
+const connection = await mysql.createConnection({ /* ... */ });
+const executor = createMysqlExecutor(connection);
+
 const ctx = new OrmContext({
   dialect: new MySqlDialect(),
-  executor: {
-    async executeSql(sql, params) {
-      const [rows] = await connection.execute(sql, params);
-      // MetalORM expects columns + values; adapt as needed
-      return [{
-        columns: Object.keys(rows[0] ?? {}),
-        values: rows.map(row => Object.values(row)),
-      }];
-    },
-    // Optional: if you want MetalORM to handle transactions around saveChanges()
-    async beginTransaction() {
-      await connection.beginTransaction();
-    },
-    async commitTransaction() {
-      await connection.commit();
-    },
-    async rollbackTransaction() {
-      await connection.rollback();
-    },
-  },
+  executor,
 });
 
 // 2) Load entities with lazy relations
@@ -380,7 +381,7 @@ class User {
   @PrimaryKey(col.int())
   id!: number;
 
-  @Column(col.varchar(255).notNull())
+  @Column(col.varchar(255))
   name!: string;
 
   @Column(col.varchar(255))
@@ -398,10 +399,10 @@ class Post {
   @PrimaryKey(col.int())
   id!: number;
 
-  @Column(col.varchar(255).notNull())
+  @Column(col.varchar(255))
   title!: string;
 
-  @Column(col.int().notNull())
+  @Column(col.int())
   userId!: number;
 
   @BelongsTo({
@@ -417,18 +418,11 @@ const tables = bootstrapEntities();
 
 // 2) Create OrmContext as before
 const connection = await mysql.createConnection({ /* ... */ });
+const executor = createMysqlExecutor(connection);
 
 const ctx = new OrmContext({
   dialect: new MySqlDialect(),
-  executor: {
-    async executeSql(sql, params) {
-      const [rows] = await connection.execute(sql, params);
-      return [{
-        columns: Object.keys(rows[0] ?? {}),
-        values: rows.map(row => Object.values(row)),
-      }];
-    },
-  },
+  executor,
 });
 
 // 3) Query starting from the entity class
@@ -475,6 +469,7 @@ Under the hood, MetalORM leans on well-known patterns:
 
 - **AST + dialect abstraction**: SQL is modeled as typed AST nodes, compiled by dialects that you can extend.
 - **Separation of concerns**: schema, AST, SQL compilation, execution, and ORM runtime are separate layers.
+- **Executor abstraction**: built-in executor creators (`createMysqlExecutor`, `createPostgresExecutor`, etc.) provide a clean separation between database drivers and ORM operations.
 - **Unit of Work + Identity Map**: `OrmContext` coordinates changes and enforces one entity instance per row, following the [Unit of Work](https://en.wikipedia.org/wiki/Unit_of_work) and [Identity map](https://en.wikipedia.org/wiki/Identity_map_pattern) patterns.
 - **Domain events + interceptors**: decouple side-effects from persistence and let cross-cutting concerns hook into flush points, similar in spirit to domain events in [Domain-driven design](https://en.wikipedia.org/wiki/Domain-driven_design).