metal-orm 1.0.51 → 1.0.53

package/README.md

@@ -74,20 +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)
-- [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)
 
 ---
@@ -249,7 +250,9 @@ console.log(rows);
 // ]
 ```
 
-That’s it: schema, query, SQL, done.
+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)
 

package/dist/index.cjs

@@ -101,6 +101,7 @@ __export(index_exports, {
   cos: () => cos,
   cot: () => cot,
   count: () => count,
+  countAll: () => countAll,
   createEntityFromRow: () => createEntityFromRow,
   createEntityProxy: () => createEntityProxy,
   createExecutorFromQueryRunner: () => createExecutorFromQueryRunner,
@@ -163,6 +164,7 @@ __export(index_exports, {
   isValueOperandInput: () => isValueOperandInput,
   isWindowFunctionNode: () => isWindowFunctionNode,
   jsonPath: () => jsonPath,
+  jsonify: () => jsonify,
   lag: () => lag,
   lastValue: () => lastValue,
   lead: () => lead,
@@ -873,6 +875,11 @@ var sum = buildAggregate("SUM");
 var avg = buildAggregate("AVG");
 var min = buildAggregate("MIN");
 var max = buildAggregate("MAX");
+var countAll = () => ({
+  type: "Function",
+  name: "COUNT",
+  args: []
+});
 var toOrderByNode = (order) => ({
   type: "OrderBy",
   term: columnOperand(order.column),
@@ -1075,7 +1082,7 @@ var StandardFunctionStrategy = class _StandardFunctionStrategy {
     this.registerStandard();
   }
   registerStandard() {
-    this.add("COUNT", ({ compiledArgs }) => `COUNT(${compiledArgs.join(", ")})`);
+    this.add("COUNT", ({ compiledArgs }) => compiledArgs.length ? `COUNT(${compiledArgs.join(", ")})` : "COUNT(*)");
     this.add("SUM", ({ compiledArgs }) => `SUM(${compiledArgs[0]})`);
     this.add("AVG", ({ compiledArgs }) => `AVG(${compiledArgs[0]})`);
     this.add("MIN", ({ compiledArgs }) => `MIN(${compiledArgs[0]})`);
@@ -5001,10 +5008,10 @@ var flattenResults = (results) => {
   }
   return rows;
 };
-var executeWithEntityContext = async (entityCtx, qb) => {
+var executeWithContexts = async (execCtx, entityCtx, qb) => {
   const ast = qb.getAST();
-  const compiled = entityCtx.dialect.compileSelect(ast);
-  const executed = await entityCtx.executor.executeSql(compiled.sql, compiled.params);
+  const compiled = execCtx.dialect.compileSelect(ast);
+  const executed = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
   const rows = flattenResults(executed);
   if (ast.setOps && ast.setOps.length > 0) {
     return rows.map((row) => createEntityProxy(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
@@ -5013,14 +5020,14 @@ var executeWithEntityContext = async (entityCtx, qb) => {
   return hydrated.map((row) => createEntityFromRow(entityCtx, qb.getTable(), row, qb.getLazyRelations()));
 };
 async function executeHydrated(session, qb) {
-  return executeWithEntityContext(session, qb);
+  return executeWithContexts(session.getExecutionContext(), session, qb);
 }
-async function executeHydratedWithContexts(_execCtx, hydCtx, qb) {
+async function executeHydratedWithContexts(execCtx, hydCtx, qb) {
   const entityCtx = hydCtx.entityContext;
   if (!entityCtx) {
     throw new Error("Hydration context is missing an EntityContext");
   }
-  return executeWithEntityContext(entityCtx, qb);
+  return executeWithContexts(execCtx, entityCtx, qb);
 }
 
 // src/query-builder/query-resolution.ts
@@ -5374,6 +5381,52 @@ var SelectQueryBuilder = class _SelectQueryBuilder {
   async execute(ctx) {
     return executeHydrated(ctx, this);
   }
+  withAst(ast) {
+    const nextState = new SelectQueryState(this.env.table, ast);
+    const nextContext = {
+      ...this.context,
+      state: nextState
+    };
+    return this.clone(nextContext);
+  }
+  async count(session) {
+    const unpagedAst = {
+      ...this.context.state.ast,
+      orderBy: void 0,
+      limit: void 0,
+      offset: void 0
+    };
+    const subAst = this.withAst(unpagedAst).getAST();
+    const countQuery = {
+      type: "SelectQuery",
+      from: derivedTable(subAst, "__metal_count"),
+      columns: [{ type: "Function", name: "COUNT", args: [], alias: "total" }],
+      joins: []
+    };
+    const execCtx = session.getExecutionContext();
+    const compiled = execCtx.dialect.compileSelect(countQuery);
+    const results = await execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
+    const value = results[0]?.values?.[0]?.[0];
+    if (typeof value === "number") return value;
+    if (typeof value === "bigint") return Number(value);
+    if (typeof value === "string") return Number(value);
+    return value === null || value === void 0 ? 0 : Number(value);
+  }
+  async executePaged(session, options) {
+    const { page, pageSize } = options;
+    if (!Number.isInteger(page) || page < 1) {
+      throw new Error("executePaged: page must be an integer >= 1");
+    }
+    if (!Number.isInteger(pageSize) || pageSize < 1) {
+      throw new Error("executePaged: pageSize must be an integer >= 1");
+    }
+    const offset = (page - 1) * pageSize;
+    const [items, totalItems] = await Promise.all([
+      this.limit(pageSize).offset(offset).execute(session),
+      this.count(session)
+    ]);
+    return { items, totalItems };
+  }
   /**
    * Executes the query with provided execution and hydration contexts
    * @param execCtx - Execution context
@@ -6223,8 +6276,9 @@ var UpdateQueryBuilder = class _UpdateQueryBuilder {
    * @returns A promise that resolves to the query results
    */
   async execute(session) {
-    const compiled = this.compile(session.dialect);
-    return session.executor.executeSql(compiled.sql, compiled.params);
+    const execCtx = session.getExecutionContext();
+    const compiled = this.compile(execCtx.dialect);
+    return execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
   }
   /**
    * Returns the Abstract Syntax Tree (AST) representation of the query
@@ -6408,8 +6462,9 @@ var DeleteQueryBuilder = class _DeleteQueryBuilder {
    * @returns A promise that resolves to the query results
    */
   async execute(session) {
-    const compiled = this.compile(session.dialect);
-    return session.executor.executeSql(compiled.sql, compiled.params);
+    const execCtx = session.getExecutionContext();
+    const compiled = this.compile(execCtx.dialect);
+    return execCtx.interceptors.run({ sql: compiled.sql, params: compiled.params }, execCtx.executor);
   }
   /**
    * Returns the Abstract Syntax Tree (AST) representation of the query
@@ -9521,18 +9576,30 @@ var runInTransaction = async (executor, action) => {
 
 // src/orm/save-graph.ts
 var toKey8 = (value) => value === null || value === void 0 ? "" : String(value);
-var pickColumns = (table, payload) => {
+var coerceColumnValue = (table, columnName, value, options) => {
+  if (options.coerce !== "json") return value;
+  if (value === null || value === void 0) return value;
+  const column = table.columns[columnName];
+  if (!column) return value;
+  const normalized = normalizeColumnType(column.type);
+  const isDateLikeColumn = normalized === "date" || normalized === "datetime" || normalized === "timestamp" || normalized === "timestamptz";
+  if (isDateLikeColumn && value instanceof Date) {
+    return value.toISOString();
+  }
+  return value;
+};
+var pickColumns = (table, payload, options) => {
   const columns = {};
   for (const key of Object.keys(table.columns)) {
     if (payload[key] !== void 0) {
-      columns[key] = payload[key];
+      columns[key] = coerceColumnValue(table, key, payload[key], options);
     }
   }
   return columns;
 };
-var ensureEntity = (session, table, payload) => {
+var ensureEntity = (session, table, payload, options) => {
   const pk = findPrimaryKey(table);
-  const row = pickColumns(table, payload);
+  const row = pickColumns(table, payload, options);
   const pkValue = payload[pk];
   if (pkValue !== void 0 && pkValue !== null) {
     const tracked = session.getEntity(table, pkValue);
@@ -9545,10 +9612,10 @@ var ensureEntity = (session, table, payload) => {
   }
   return createEntityFromRow(session, table, row);
 };
-var assignColumns = (table, entity, payload) => {
+var assignColumns = (table, entity, payload, options) => {
   for (const key of Object.keys(table.columns)) {
     if (payload[key] !== void 0) {
-      entity[key] = payload[key];
+      entity[key] = coerceColumnValue(table, key, payload[key], options);
     }
   }
 };
@@ -9575,8 +9642,8 @@ var handleHasMany = async (session, root, relationName, relation, payload, optio
     const asObj = typeof item === "object" ? item : { [targetPk]: item };
     const pkValue = asObj[targetPk];
     const current = findInCollectionByPk(existing, targetPk, pkValue) ?? (pkValue !== void 0 && pkValue !== null ? session.getEntity(targetTable, pkValue) : void 0);
-    const entity = current ?? ensureEntity(session, targetTable, asObj);
-    assignColumns(targetTable, entity, asObj);
+    const entity = current ?? ensureEntity(session, targetTable, asObj, options);
+    assignColumns(targetTable, entity, asObj, options);
     await applyGraphToEntity(session, targetTable, entity, asObj, options);
     if (!isEntityInCollection(collection.getItems(), targetPk, entity)) {
       collection.attach(entity);
@@ -9651,8 +9718,8 @@ var handleBelongsToMany = async (session, root, relationName, relation, payload,
     }
     const asObj = item;
     const pkValue = asObj[targetPk];
-    const entity = pkValue !== void 0 && pkValue !== null ? session.getEntity(targetTable, pkValue) ?? ensureEntity(session, targetTable, asObj) : ensureEntity(session, targetTable, asObj);
-    assignColumns(targetTable, entity, asObj);
+    const entity = pkValue !== void 0 && pkValue !== null ? session.getEntity(targetTable, pkValue) ?? ensureEntity(session, targetTable, asObj, options) : ensureEntity(session, targetTable, asObj, options);
+    assignColumns(targetTable, entity, asObj, options);
     await applyGraphToEntity(session, targetTable, entity, asObj, options);
     if (!isEntityInCollection(collection.getItems(), targetPk, entity)) {
       collection.attach(entity);
@@ -9683,7 +9750,7 @@ var applyRelation = async (session, table, entity, relationName, relation, paylo
   }
 };
 var applyGraphToEntity = async (session, table, entity, payload, options) => {
-  assignColumns(table, entity, payload);
+  assignColumns(table, entity, payload, options);
   for (const [relationName, relation] of Object.entries(table.relations)) {
     if (!(relationName in payload)) continue;
     await applyRelation(session, table, entity, relationName, relation, payload[relationName], options);
@@ -9694,7 +9761,7 @@ var saveGraphInternal = async (session, entityClass, payload, options = {}) => {
   if (!table) {
     throw new Error("Entity metadata has not been bootstrapped");
   }
-  const root = ensureEntity(session, table, payload);
+  const root = ensureEntity(session, table, payload, options);
   await applyGraphToEntity(session, table, root, payload, options);
   return root;
 };
@@ -9877,13 +9944,6 @@ var OrmSession = class {
   async findMany(qb) {
     return executeHydrated(this, qb);
   }
-  /**
-   * Saves an entity graph (root + nested relations) based on a DTO-like payload.
-   * @param entityClass - Root entity constructor
-   * @param payload - DTO payload containing column values and nested relations
-   * @param options - Graph save options
-   * @returns The root entity instance
-   */
   async saveGraph(entityClass, payload, options) {
     const { transactional = true, ...graphOptions } = options ?? {};
     const execute = () => saveGraphInternal(this, entityClass, payload, graphOptions);
@@ -10084,6 +10144,17 @@ var Orm = class {
   }
 };
 
+// src/orm/jsonify.ts
+var jsonify = (value) => {
+  const record = value;
+  const result = {};
+  for (const key of Object.keys(record)) {
+    const entry = record[key];
+    result[key] = entry instanceof Date ? entry.toISOString() : entry;
+  }
+  return result;
+};
+
 // src/decorators/decorator-metadata.ts
 var METADATA_KEY = "metal-orm:decorators";
 var isStandardDecoratorContext = (value) => {
@@ -10906,6 +10977,7 @@ function createPooledExecutorFactory(opts) {
   cos,
   cot,
   count,
+  countAll,
   createEntityFromRow,
   createEntityProxy,
   createExecutorFromQueryRunner,
@@ -10968,6 +11040,7 @@ function createPooledExecutorFactory(opts) {
   isValueOperandInput,
   isWindowFunctionNode,
   jsonPath,
+  jsonify,
   lag,
   lastValue,
   lead,