metal-orm 1.0.12 → 1.0.14

package/README.md

@@ -1,11 +1,9 @@
-# MetalORM ⚙️
+# MetalORM ⚙️ - Type-safe SQL, layered ORM, decorator-based entities – all on the same core.
 
 [![npm version](https://img.shields.io/npm/v/metal-orm.svg)](https://www.npmjs.com/package/metal-orm)
 [![license](https://img.shields.io/npm/l/metal-orm.svg)](https://github.com/celsowm/metal-orm/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%23007ACC.svg)](https://www.typescriptlang.org/)
 
-**Type-safe SQL, layered ORM, decorator-based entities – all on the same core.**
-
 MetalORM is a TypeScript-first, AST-driven SQL toolkit you can dial up or down depending on how “ORM-y” you want to be:
 
 - **Level 1 – Query builder & hydration 🧩**  
@@ -22,10 +20,10 @@ Use only the layer you need in each part of your codebase.
 <a id="table-of-contents"></a>
 ## Table of Contents 🧭
 
-- [Documentation](#documentation)
-- [Features](#features)
-- [Installation](#installation)
-- [Quick start - three levels](#quick-start)
+- [Documentation](#documentation)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick start - three levels](#quick-start)
   - [Level 1 – Query builder & hydration](#level-1)
   - [Level 2 – Entities + Unit of Work](#level-2)
   - [Level 3 – Decorator entities](#level-3)
@@ -41,18 +39,18 @@ Use only the layer you need in each part of your codebase.
 
 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)
-- [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)
+- [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)
+- [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)
 
 ---
 
@@ -65,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.
+- **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.
 - **Multi-dialect**: compile once, run on MySQL/MariaDB, PostgreSQL, SQLite, or SQL Server via pluggable dialects.
@@ -88,6 +87,7 @@ On top of the query builder, MetalORM ships a focused runtime:
 - **Relation change processor** that knows how to deal with has-many and many-to-many pivot tables.
 - **Interceptors**: `beforeFlush` / `afterFlush` hooks for cross-cutting concerns (auditing, multi-tenant filters, soft delete filters, etc.).
 - **Domain events**: `addDomainEvent` and a DomainEventBus integrated into `saveChanges()`, aligned with domain events from [Domain-driven design](https://en.wikipedia.org/wiki/Domain-driven_design).
+- **JSON-safe entities**: relation wrappers hide internal references and implement `toJSON`, so `JSON.stringify` of hydrated entities works without circular reference errors.
 
 Use this layer where:
 
@@ -494,4 +494,4 @@ See the contributing guide for details.
 <a id="license"></a>
 ## License 📄
 
-MetalORM is MIT licensed.
+MetalORM is MIT licensed.

package/dist/decorators/index.cjs

@@ -500,6 +500,44 @@ var SelectQueryState = class _SelectQueryState {
       ctes: [...this.ast.ctes ?? [], cte]
     });
   }
+  /**
+   * Adds a set operation (UNION/INTERSECT/EXCEPT) to the query
+   * @param op - Set operation node to add
+   * @returns New SelectQueryState with set operation
+   */
+  withSetOperation(op) {
+    return this.clone({
+      ...this.ast,
+      setOps: [...this.ast.setOps ?? [], op]
+    });
+  }
+};
+
+// src/core/ast/join-node.ts
+var createJoinNode = (kind, tableName, condition, relationName) => ({
+  type: "Join",
+  kind,
+  table: { type: "Table", name: tableName },
+  condition,
+  relationName
+});
+
+// src/core/sql/sql.ts
+var JOIN_KINDS = {
+  /** INNER JOIN type */
+  INNER: "INNER",
+  /** LEFT JOIN type */
+  LEFT: "LEFT",
+  /** RIGHT JOIN type */
+  RIGHT: "RIGHT",
+  /** CROSS JOIN type */
+  CROSS: "CROSS"
+};
+var ORDER_DIRECTIONS = {
+  /** Ascending order */
+  ASC: "ASC",
+  /** Descending order */
+  DESC: "DESC"
 };
 
 // src/query-builder/hydration-manager.ts
@@ -551,8 +589,26 @@ var HydrationManager = class _HydrationManager {
    * @returns AST with hydration metadata
    */
   applyToAst(ast) {
+    if (ast.setOps && ast.setOps.length > 0) {
+      return ast;
+    }
     const plan = this.planner.getPlan();
     if (!plan) return ast;
+    const needsPaginationGuard = this.requiresParentPagination(ast, plan);
+    const rewritten = needsPaginationGuard ? this.wrapForParentPagination(ast, plan) : ast;
+    return this.attachHydrationMeta(rewritten, plan);
+  }
+  /**
+   * Gets the current hydration plan
+   * @returns Hydration plan or undefined if none exists
+   */
+  getPlan() {
+    return this.planner.getPlan();
+  }
+  /**
+   * Attaches hydration metadata to a query AST node.
+   */
+  attachHydrationMeta(ast, plan) {
     return {
       ...ast,
       meta: {
@@ -562,11 +618,154 @@ var HydrationManager = class _HydrationManager {
     };
   }
   /**
-   * Gets the current hydration plan
-   * @returns Hydration plan or undefined if none exists
+   * Determines whether the query needs pagination rewriting to keep LIMIT/OFFSET
+   * applied to parent rows when eager-loading multiplicative relations.
    */
-  getPlan() {
-    return this.planner.getPlan();
+  requiresParentPagination(ast, plan) {
+    const hasPagination = ast.limit !== void 0 || ast.offset !== void 0;
+    return hasPagination && this.hasMultiplyingRelations(plan);
+  }
+  hasMultiplyingRelations(plan) {
+    return plan.relations.some(
+      (rel) => rel.type === RelationKinds.HasMany || rel.type === RelationKinds.BelongsToMany
+    );
+  }
+  /**
+   * Rewrites the query using CTEs so LIMIT/OFFSET target distinct parent rows
+   * instead of the joined result set.
+   *
+   * The strategy:
+   * - Hoist the original query (minus limit/offset) into a base CTE.
+   * - Select distinct parent ids from that base CTE with the original ordering and pagination.
+   * - Join the base CTE against the paged ids to retrieve the joined rows for just that page.
+   */
+  wrapForParentPagination(ast, plan) {
+    const projectionNames = this.getProjectionNames(ast.columns);
+    if (!projectionNames) {
+      return ast;
+    }
+    const projectionAliases = this.buildProjectionAliasMap(ast.columns);
+    const projectionSet = new Set(projectionNames);
+    const rootPkAlias = projectionAliases.get(`${plan.rootTable}.${plan.rootPrimaryKey}`) ?? plan.rootPrimaryKey;
+    const baseCteName = this.nextCteName(ast.ctes, "__metal_pagination_base");
+    const baseQuery = {
+      ...ast,
+      ctes: void 0,
+      limit: void 0,
+      offset: void 0,
+      orderBy: void 0,
+      meta: void 0
+    };
+    const baseCte = {
+      type: "CommonTableExpression",
+      name: baseCteName,
+      query: baseQuery,
+      recursive: false
+    };
+    const orderBy = this.mapOrderBy(ast.orderBy, plan, projectionAliases, baseCteName, projectionSet);
+    if (orderBy === null) {
+      return ast;
+    }
+    const pageCteName = this.nextCteName([...ast.ctes ?? [], baseCte], "__metal_pagination_page");
+    const pagingColumns = this.buildPagingColumns(rootPkAlias, orderBy, baseCteName);
+    const pageCte = {
+      type: "CommonTableExpression",
+      name: pageCteName,
+      query: {
+        type: "SelectQuery",
+        from: { type: "Table", name: baseCteName },
+        columns: pagingColumns,
+        joins: [],
+        distinct: [{ type: "Column", table: baseCteName, name: rootPkAlias }],
+        orderBy,
+        limit: ast.limit,
+        offset: ast.offset
+      },
+      recursive: false
+    };
+    const joinCondition = eq(
+      { type: "Column", table: baseCteName, name: rootPkAlias },
+      { type: "Column", table: pageCteName, name: rootPkAlias }
+    );
+    const outerColumns = projectionNames.map((name) => ({
+      type: "Column",
+      table: baseCteName,
+      name,
+      alias: name
+    }));
+    return {
+      type: "SelectQuery",
+      from: { type: "Table", name: baseCteName },
+      columns: outerColumns,
+      joins: [createJoinNode(JOIN_KINDS.INNER, pageCteName, joinCondition)],
+      orderBy,
+      ctes: [...ast.ctes ?? [], baseCte, pageCte]
+    };
+  }
+  nextCteName(existing, baseName) {
+    const names = new Set((existing ?? []).map((cte) => cte.name));
+    let candidate = baseName;
+    let suffix = 1;
+    while (names.has(candidate)) {
+      suffix += 1;
+      candidate = `${baseName}_${suffix}`;
+    }
+    return candidate;
+  }
+  getProjectionNames(columns) {
+    const names = [];
+    for (const col of columns) {
+      const alias = col.alias ?? col.name;
+      if (!alias) return void 0;
+      names.push(alias);
+    }
+    return names;
+  }
+  buildProjectionAliasMap(columns) {
+    const map = /* @__PURE__ */ new Map();
+    for (const col of columns) {
+      if (col.type !== "Column") continue;
+      const node = col;
+      const key = `${node.table}.${node.name}`;
+      map.set(key, node.alias ?? node.name);
+    }
+    return map;
+  }
+  mapOrderBy(orderBy, plan, projectionAliases, baseAlias, availableColumns) {
+    if (!orderBy || orderBy.length === 0) {
+      return void 0;
+    }
+    const mapped = [];
+    for (const ob of orderBy) {
+      if (ob.column.table !== plan.rootTable) {
+        return null;
+      }
+      const alias = projectionAliases.get(`${ob.column.table}.${ob.column.name}`) ?? ob.column.name;
+      if (!availableColumns.has(alias)) {
+        return null;
+      }
+      mapped.push({
+        type: "OrderBy",
+        column: { type: "Column", table: baseAlias, name: alias },
+        direction: ob.direction
+      });
+    }
+    return mapped;
+  }
+  buildPagingColumns(primaryKey, orderBy, tableAlias) {
+    const columns = [{ type: "Column", table: tableAlias, name: primaryKey, alias: primaryKey }];
+    if (!orderBy) return columns;
+    for (const ob of orderBy) {
+      if (!columns.some((col) => col.name === ob.column.name)) {
+        columns.push({
+          type: "Column",
+          table: tableAlias,
+          name: ob.column.name,
+          alias: ob.column.name
+        });
+      }
+    }
+    return columns;
   }
 };
 
@@ -820,6 +1019,20 @@ var QueryAstService = class {
     };
     return this.state.withCte(cte);
   }
+  /**
+   * Adds a set operation (UNION/UNION ALL/INTERSECT/EXCEPT) to the query
+   * @param operator - Set operator
+   * @param query - Right-hand side query
+   * @returns Updated query state with set operation
+   */
+  withSetOperation(operator, query) {
+    const op = {
+      type: "SetOperation",
+      operator,
+      query
+    };
+    return this.state.withSetOperation(op);
+  }
   /**
    * Selects a subquery as a column
    * @param alias - Alias for the subquery
@@ -972,15 +1185,6 @@ var RelationProjectionHelper = class {
   }
 };
 
-// src/core/ast/join-node.ts
-var createJoinNode = (kind, tableName, condition, relationName) => ({
-  type: "Join",
-  kind,
-  table: { type: "Table", name: tableName },
-  condition,
-  relationName
-});
-
 // src/query-builder/relation-conditions.ts
 var assertNever = (value) => {
   throw new Error(`Unhandled relation type: ${JSON.stringify(value)}`);
@@ -1036,24 +1240,6 @@ var buildRelationCorrelation = (root, relation) => {
   return baseRelationCondition(root, relation);
 };
 
-// src/core/sql/sql.ts
-var JOIN_KINDS = {
-  /** INNER JOIN type */
-  INNER: "INNER",
-  /** LEFT JOIN type */
-  LEFT: "LEFT",
-  /** RIGHT JOIN type */
-  RIGHT: "RIGHT",
-  /** CROSS JOIN type */
-  CROSS: "CROSS"
-};
-var ORDER_DIRECTIONS = {
-  /** Ascending order */
-  ASC: "ASC",
-  /** Descending order */
-  DESC: "DESC"
-};
-
 // src/query-builder/relation-service.ts
 var RelationService = class {
   /**
@@ -1499,6 +1685,16 @@ var hasEntityMeta = (entity) => {
 
 // src/orm/relations/has-many.ts
 var toKey2 = (value) => value === null || value === void 0 ? "" : String(value);
+var hideInternal = (obj, keys) => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
 var DefaultHasManyCollection = class {
   constructor(ctx, meta, root, relationName, relation, rootTable, loader, createEntity, localKey) {
     this.ctx = ctx;
@@ -1514,6 +1710,7 @@ var DefaultHasManyCollection = class {
     this.items = [];
     this.added = /* @__PURE__ */ new Set();
     this.removed = /* @__PURE__ */ new Set();
+    hideInternal(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "localKey"]);
     this.hydrateFromCache();
   }
   async load() {
@@ -1589,10 +1786,23 @@ var DefaultHasManyCollection = class {
     this.items = rows.map((row) => this.createEntity(row));
     this.loaded = true;
   }
+  toJSON() {
+    return this.items;
+  }
 };
 
 // src/orm/relations/belongs-to.ts
 var toKey3 = (value) => value === null || value === void 0 ? "" : String(value);
+var hideInternal2 = (obj, keys) => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
 var DefaultBelongsToReference = class {
   constructor(ctx, meta, root, relationName, relation, rootTable, loader, createEntity, targetKey) {
     this.ctx = ctx;
@@ -1606,6 +1816,7 @@ var DefaultBelongsToReference = class {
     this.targetKey = targetKey;
     this.loaded = false;
     this.current = null;
+    hideInternal2(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "targetKey"]);
     this.populateFromHydrationCache();
   }
   async load() {
@@ -1666,10 +1877,23 @@ var DefaultBelongsToReference = class {
     this.current = this.createEntity(row);
     this.loaded = true;
   }
+  toJSON() {
+    return this.current;
+  }
 };
 
 // src/orm/relations/many-to-many.ts
 var toKey4 = (value) => value === null || value === void 0 ? "" : String(value);
+var hideInternal3 = (obj, keys) => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
 var DefaultManyToManyCollection = class {
   constructor(ctx, meta, root, relationName, relation, rootTable, loader, createEntity, localKey) {
     this.ctx = ctx;
@@ -1683,6 +1907,7 @@ var DefaultManyToManyCollection = class {
     this.localKey = localKey;
     this.loaded = false;
     this.items = [];
+    hideInternal3(this, ["ctx", "meta", "root", "relationName", "relation", "rootTable", "loader", "createEntity", "localKey"]);
     this.hydrateFromCache();
   }
   async load() {
@@ -1788,6 +2013,9 @@ var DefaultManyToManyCollection = class {
     });
     this.loaded = true;
   }
+  toJSON() {
+    return this.items;
+  }
 };
 
 // src/orm/lazy-batch.ts
@@ -2148,9 +2376,15 @@ var flattenResults = (results) => {
   return rows;
 };
 async function executeHydrated(ctx, qb) {
-  const compiled = ctx.dialect.compileSelect(qb.getAST());
+  const ast = qb.getAST();
+  const compiled = ctx.dialect.compileSelect(ast);
   const executed = await ctx.executor.executeSql(compiled.sql, compiled.params);
   const rows = flattenResults(executed);
+  if (ast.setOps && ast.setOps.length > 0) {
+    return rows.map(
+      (row) => createEntityProxy(ctx, qb.getTable(), row, qb.getLazyRelations())
+    );
+  }
   const hydrated = hydrateRows(rows, qb.getHydrationPlan());
   return hydrated.map(
     (row) => createEntityFromRow(ctx, qb.getTable(), row, qb.getLazyRelations())
@@ -2197,6 +2431,10 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     const joinNode = createJoinNode(kind, table.name, condition);
     return this.applyAst(context, (service) => service.withJoin(joinNode));
   }
+  applySetOperation(operator, query) {
+    const subAst = this.resolveQueryNode(query);
+    return this.applyAst(this.context, (service) => service.withSetOperation(operator, subAst));
+  }
   /**
    * Selects specific columns for the query
    * @param columns - Record of column definitions, function nodes, case expressions, or window functions
@@ -2385,6 +2623,38 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
     const nextContext = this.applyAst(this.context, (service) => service.withOffset(n));
     return this.clone(nextContext);
   }
+  /**
+   * Combines this query with another using UNION
+   * @param query - Query to union with
+   * @returns New query builder instance with the set operation
+   */
+  union(query) {
+    return this.clone(this.applySetOperation("UNION", query));
+  }
+  /**
+   * Combines this query with another using UNION ALL
+   * @param query - Query to union with
+   * @returns New query builder instance with the set operation
+   */
+  unionAll(query) {
+    return this.clone(this.applySetOperation("UNION ALL", query));
+  }
+  /**
+   * Combines this query with another using INTERSECT
+   * @param query - Query to intersect with
+   * @returns New query builder instance with the set operation
+   */
+  intersect(query) {
+    return this.clone(this.applySetOperation("INTERSECT", query));
+  }
+  /**
+   * Combines this query with another using EXCEPT
+   * @param query - Query to subtract
+   * @returns New query builder instance with the set operation
+   */
+  except(query) {
+    return this.clone(this.applySetOperation("EXCEPT", query));
+  }
   /**
    * Adds a WHERE EXISTS condition to the query
    * @param subquery - Subquery to check for existence