metal-orm 1.0.50 → 1.0.52

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)
 
 ---

package/dist/index.cjs

@@ -163,6 +163,7 @@ __export(index_exports, {
   isValueOperandInput: () => isValueOperandInput,
   isWindowFunctionNode: () => isWindowFunctionNode,
   jsonPath: () => jsonPath,
+  jsonify: () => jsonify,
   lag: () => lag,
   lastValue: () => lastValue,
   lead: () => lead,
@@ -379,6 +380,10 @@ var col = {
    * @returns ColumnDef with VARCHAR type
    */
   varchar: (length2) => ({ name: "", type: "VARCHAR", args: [length2] }),
+  /**
+   * Creates a text column definition
+   */
+  text: () => ({ name: "", type: "TEXT" }),
   /**
    * Creates a fixed precision decimal column definition
    */
@@ -6887,6 +6892,29 @@ var postgresIntrospector = {
       if (!trimmed) return;
       columnComments.set(key, trimmed);
     });
+    const tableCommentRows = await queryRows(
+      ctx.executor,
+      `
+      SELECT
+        ns.nspname AS table_schema,
+        cls.relname AS table_name,
+        pg_catalog.obj_description(cls.oid) AS description
+      FROM pg_catalog.pg_class cls
+      JOIN pg_catalog.pg_namespace ns ON ns.oid = cls.relnamespace
+      WHERE ns.nspname = $1
+        AND cls.relkind IN ('r', 'p')
+      `,
+      [schema]
+    );
+    const tableComments = /* @__PURE__ */ new Map();
+    tableCommentRows.forEach((r) => {
+      if (!shouldIncludeTable(r.table_name, options)) return;
+      if (!r.description) return;
+      const key = `${r.table_schema}.${r.table_name}`;
+      const trimmed = r.description.trim();
+      if (!trimmed) return;
+      tableComments.set(key, trimmed);
+    });
     const qbPk = new SelectQueryBuilder(PgKeyColumnUsage).select({
       table_schema: PgKeyColumnUsage.columns.table_schema,
       table_name: PgKeyColumnUsage.columns.table_name,
@@ -7027,7 +7055,8 @@ var postgresIntrospector = {
           schema: r.table_schema,
           columns: [],
           primaryKey: pkMap.get(key) || [],
-          indexes: []
+          indexes: [],
+          comment: tableComments.get(key)
         });
       }
       const cols = tablesByKey.get(key);
@@ -7412,6 +7441,53 @@ var runPragma = async (name, table, alias, columnAliases, ctx) => {
   const query = buildPragmaQuery(name, table, alias, columnAliases);
   return await runSelectNode(query, ctx);
 };
+var loadSqliteSchemaComments = async (ctx) => {
+  const tableComments = /* @__PURE__ */ new Map();
+  const columnComments = /* @__PURE__ */ new Map();
+  const tableExists = await queryRows(
+    ctx.executor,
+    `SELECT name FROM sqlite_master WHERE type='table' AND name='schema_comments' LIMIT 1`
+  );
+  if (!tableExists.length) {
+    return { tableComments, columnComments };
+  }
+  const commentRows = await queryRows(
+    ctx.executor,
+    `SELECT object_type, schema_name, table_name, column_name, comment FROM schema_comments`
+  );
+  for (const row of commentRows) {
+    const objectType = typeof row.object_type === "string" ? row.object_type.toLowerCase() : "";
+    const tableName = typeof row.table_name === "string" ? row.table_name : "";
+    if (!tableName) continue;
+    const columnName = typeof row.column_name === "string" ? row.column_name : "";
+    const schemaName = typeof row.schema_name === "string" ? row.schema_name : "";
+    const rawComment = row.comment;
+    if (rawComment == null) continue;
+    const commentText = String(rawComment).trim();
+    if (!commentText) continue;
+    const addTableComment = () => {
+      tableComments.set(tableName, commentText);
+      if (schemaName) {
+        tableComments.set(`${schemaName}.${tableName}`, commentText);
+      }
+    };
+    const addColumnComment = () => {
+      columnComments.set(`${tableName}.${columnName}`, commentText);
+      if (schemaName) {
+        columnComments.set(`${schemaName}.${tableName}.${columnName}`, commentText);
+      }
+    };
+    if (objectType === "table") {
+      addTableComment();
+    } else if (objectType === "column" && columnName) {
+      addColumnComment();
+    }
+  }
+  return {
+    tableComments,
+    columnComments
+  };
+};
 var sqliteIntrospector = {
   async introspect(ctx, options) {
     const alias = "sqlite_master";
@@ -7425,6 +7501,7 @@ var sqliteIntrospector = {
         notLike(columnNode2(alias, "name"), "sqlite_%")
       )
     };
+    const { tableComments, columnComments } = await loadSqliteSchemaComments(ctx);
     const tableRows = await runSelectNode(tablesQuery, ctx);
     const tables = [];
     for (const row of tableRows) {
@@ -7451,15 +7528,26 @@ var sqliteIntrospector = {
         ["seq", "name", "unique"],
         ctx
       );
-      const tableEntry = { name: tableName, columns: [], primaryKey: [], indexes: [] };
+      const tableEntry = {
+        name: tableName,
+        columns: [],
+        primaryKey: [],
+        indexes: [],
+        comment: tableComments.get(tableName)
+      };
       tableInfo.forEach((info) => {
-        tableEntry.columns.push({
+        const column = {
           name: info.name,
           type: info.type,
           notNull: info.notnull === 1,
           default: info.dflt_value ?? void 0,
           autoIncrement: false
-        });
+        };
+        const columnComment = columnComments.get(`${tableName}.${info.name}`);
+        if (columnComment) {
+          column.comment = columnComment;
+        }
+        tableEntry.columns.push(column);
         if (info.pk && info.pk > 0) {
           tableEntry.primaryKey = tableEntry.primaryKey || [];
           tableEntry.primaryKey.push(info.name);
@@ -7731,6 +7819,60 @@ var mssqlIntrospector = {
   async introspect(ctx, options) {
     const schema = options.schema;
     const schemaCondition = schema ? eq(columnNode3("sch", "name"), schema) : void 0;
+    const schemaFilter = schema ? "AND sch.name = @p1" : "";
+    const schemaParams = schema ? [schema] : [];
+    const tableCommentRows = await queryRows(
+      ctx.executor,
+      `
+      SELECT
+        sch.name AS table_schema,
+        t.name AS table_name,
+        CONVERT(nvarchar(4000), ep.value) AS comment
+      FROM sys.extended_properties ep
+      JOIN sys.tables t ON t.object_id = ep.major_id
+      JOIN sys.schemas sch ON sch.schema_id = t.schema_id
+      WHERE ep.class = 1
+        AND ep.minor_id = 0
+        AND ep.name = 'MS_Description'
+        ${schemaFilter}
+      `,
+      schemaParams
+    );
+    const columnCommentRows = await queryRows(
+      ctx.executor,
+      `
+      SELECT
+        sch.name AS table_schema,
+        t.name AS table_name,
+        col.name AS column_name,
+        CONVERT(nvarchar(4000), ep.value) AS comment
+      FROM sys.extended_properties ep
+      JOIN sys.columns col ON col.object_id = ep.major_id AND col.column_id = ep.minor_id
+      JOIN sys.tables t ON t.object_id = col.object_id
+      JOIN sys.schemas sch ON sch.schema_id = t.schema_id
+      WHERE ep.class = 1
+        AND ep.minor_id > 0
+        AND ep.name = 'MS_Description'
+        ${schemaFilter}
+      `,
+      schemaParams
+    );
+    const tableComments = /* @__PURE__ */ new Map();
+    tableCommentRows.forEach((r) => {
+      if (!shouldIncludeTable(r.table_name, options)) return;
+      if (!r.comment) return;
+      const trimmed = r.comment.trim();
+      if (!trimmed) return;
+      tableComments.set(`${r.table_schema}.${r.table_name}`, trimmed);
+    });
+    const columnComments = /* @__PURE__ */ new Map();
+    columnCommentRows.forEach((r) => {
+      if (!shouldIncludeTable(r.table_name, options)) return;
+      if (!r.comment) return;
+      const trimmed = r.comment.trim();
+      if (!trimmed) return;
+      columnComments.set(`${r.table_schema}.${r.table_name}.${r.column_name}`, trimmed);
+    });
     const dataTypeExpression = buildMssqlDataType(
       { table: "ty", name: "name" },
       { table: "c", name: "max_length" },
@@ -8036,7 +8178,8 @@ var mssqlIntrospector = {
           schema: r.table_schema,
           columns: [],
           primaryKey: pkMap.get(key) || [],
-          indexes: []
+          indexes: [],
+          comment: tableComments.get(key)
         });
       }
       const table = tablesByKey.get(key);
@@ -8047,6 +8190,10 @@ var mssqlIntrospector = {
         default: r.column_default ?? void 0,
         autoIncrement: !!r.is_identity
       };
+      const columnComment = columnComments.get(`${key}.${r.column_name}`);
+      if (columnComment) {
+        column.comment = columnComment;
+      }
       const fk = fkMap.get(`${key}.${r.column_name}`)?.[0];
       if (fk) {
         column.references = {
@@ -9375,18 +9522,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);
@@ -9399,10 +9558,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);
     }
   }
 };
@@ -9429,8 +9588,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);
@@ -9505,8 +9664,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);
@@ -9537,7 +9696,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);
@@ -9548,7 +9707,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;
 };
@@ -9731,13 +9890,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);
@@ -9938,6 +10090,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) => {
@@ -10822,6 +10985,7 @@ function createPooledExecutorFactory(opts) {
   isValueOperandInput,
   isWindowFunctionNode,
   jsonPath,
+  jsonify,
   lag,
   lastValue,
   lead,