metal-orm 1.0.11 → 1.0.13

package/README.md

@@ -49,9 +49,10 @@ Full docs live in the `docs/` folder:
 - [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)
-- [API Reference](https://github.com/celsowm/metal-orm/blob/main/docs/api-reference.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)
 
 ---
 
@@ -61,15 +62,16 @@ Full docs live in the `docs/` folder:
 ### Level 1 – Query builder & hydration
 
 - **Declarative schema definition** with `defineTable`, `col.*`, and typed relations.
-- **Fluent query builder** over a real SQL AST  
-  (`SelectQueryBuilder`, `InsertQueryBuilder`, `UpdateQueryBuilder`, `DeleteQueryBuilder`).
-- **Advanced SQL**: CTEs, aggregates, window functions, subqueries, JSON, CASE, EXISTS.
-- **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.
-- **DML**: type-safe INSERT / UPDATE / DELETE with `RETURNING` where supported.
-
-Level 1 is ideal when you:
+- **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.
+- **DML**: type-safe INSERT / UPDATE / DELETE with `RETURNING` where supported.
+
+Level 1 is ideal when you:
 
 - Already have a domain model and just want a serious SQL builder.
 - Want deterministic SQL (no magical query generation).
@@ -81,12 +83,13 @@ On top of the query builder, MetalORM ships a focused runtime:
 
 - **Entities inferred from your `TableDef`s** (no separate mapping file).
 - **Lazy, batched relations**: `user.posts.load()`, `user.roles.syncByIds([...])`, etc.
-- **Identity map**: the same row becomes the same entity instance within a context (see the [Identity map pattern](https://en.wikipedia.org/wiki/Identity_map_pattern)).
-- **Unit of Work (`OrmContext`)** tracking New/Dirty/Removed entities and relation changes, inspired by the classic [Unit of Work pattern](https://en.wikipedia.org/wiki/Unit_of_work).
-- **Graph persistence**: mutate a whole object graph and flush once with `ctx.saveChanges()`.
-- **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).
+- **Identity map**: the same row becomes the same entity instance within a context (see the [Identity map pattern](https://en.wikipedia.org/wiki/Identity_map_pattern)).
+- **Unit of Work (`OrmContext`)** tracking New/Dirty/Removed entities and relation changes, inspired by the classic [Unit of Work pattern](https://en.wikipedia.org/wiki/Unit_of_work).
+- **Graph persistence**: mutate a whole object graph and flush once with `ctx.saveChanges()`.
+- **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:
 

package/dist/decorators/index.cjs

@@ -32,12 +32,25 @@ __export(decorators_exports, {
 module.exports = __toCommonJS(decorators_exports);
 
 // src/schema/table.ts
-var defineTable = (name, columns, relations = {}, hooks) => {
+var defineTable = (name, columns, relations = {}, hooks, options = {}) => {
   const colsWithNames = Object.entries(columns).reduce((acc, [key, def]) => {
     acc[key] = { ...def, name: key, table: name };
     return acc;
   }, {});
-  return { name, columns: colsWithNames, relations, hooks };
+  return {
+    name,
+    schema: options.schema,
+    columns: colsWithNames,
+    relations,
+    hooks,
+    primaryKey: options.primaryKey,
+    indexes: options.indexes,
+    checks: options.checks,
+    comment: options.comment,
+    engine: options.engine,
+    charset: options.charset,
+    collation: options.collation
+  };
 };
 
 // src/orm/entity-metadata.ts
@@ -487,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
@@ -538,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: {
@@ -549,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;
   }
 };
 
@@ -807,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
@@ -959,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)}`);
@@ -1023,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 {
   /**
@@ -1486,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;
@@ -1501,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() {
@@ -1576,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;
@@ -1593,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() {
@@ -1653,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;
@@ -1670,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() {
@@ -1775,6 +2013,9 @@ var DefaultManyToManyCollection = class {
     });
     this.loaded = true;
   }
+  toJSON() {
+    return this.items;
+  }
 };
 
 // src/orm/lazy-batch.ts
@@ -2135,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())
@@ -2184,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
@@ -2372,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