metal-orm 1.0.50 → 1.0.52

package/src/core/ddl/introspect/postgres.ts

@@ -54,12 +54,18 @@ type ForeignKeyEntry = {
   onUpdate?: ReferentialAction;
 };
 
-type ColumnCommentRow = {
-  table_schema: string;
-  table_name: string;
-  column_name: string;
-  description: string | null;
-};
+type ColumnCommentRow = {
+  table_schema: string;
+  table_name: string;
+  column_name: string;
+  description: string | null;
+};
+
+type TableCommentRow = {
+  table_schema: string;
+  table_name: string;
+  description: string | null;
+};
 
 /** Row type for PostgreSQL index query results from pg_catalog tables. */
 type IndexQueryRow = {
@@ -111,32 +117,55 @@ export const postgresIntrospector: SchemaIntrospector = {
       .orderBy(PgInformationSchemaColumns.columns.ordinal_position);
 
     const columnRows = await runSelect<ColumnIntrospectRow>(qbColumns, ctx);
-    const columnCommentRows = (await queryRows(
-      ctx.executor,
-      `
-      SELECT
-        ns.nspname AS table_schema,
-        cls.relname AS table_name,
-        att.attname AS column_name,
-        pg_catalog.col_description(cls.oid, att.attnum) AS description
-      FROM pg_catalog.pg_attribute att
-      JOIN pg_catalog.pg_class cls ON cls.oid = att.attrelid
-      JOIN pg_catalog.pg_namespace ns ON ns.oid = cls.relnamespace
-      WHERE ns.nspname = $1
-        AND att.attnum > 0
-        AND NOT att.attisdropped
-      `,
-      [schema]
-    )) as ColumnCommentRow[];
-    const columnComments = new Map<string, string>();
-    columnCommentRows.forEach(r => {
-      if (!shouldIncludeTable(r.table_name, options)) return;
-      if (!r.description) return;
-      const key = `${r.table_schema}.${r.table_name}.${r.column_name}`;
-      const trimmed = r.description.trim();
-      if (!trimmed) return;
-      columnComments.set(key, trimmed);
-    });
+    const columnCommentRows = (await queryRows(
+      ctx.executor,
+      `
+      SELECT
+        ns.nspname AS table_schema,
+        cls.relname AS table_name,
+        att.attname AS column_name,
+        pg_catalog.col_description(cls.oid, att.attnum) AS description
+      FROM pg_catalog.pg_attribute att
+      JOIN pg_catalog.pg_class cls ON cls.oid = att.attrelid
+      JOIN pg_catalog.pg_namespace ns ON ns.oid = cls.relnamespace
+      WHERE ns.nspname = $1
+        AND att.attnum > 0
+        AND NOT att.attisdropped
+      `,
+      [schema]
+    )) as ColumnCommentRow[];
+    const columnComments = new Map<string, string>();
+    columnCommentRows.forEach(r => {
+      if (!shouldIncludeTable(r.table_name, options)) return;
+      if (!r.description) return;
+      const key = `${r.table_schema}.${r.table_name}.${r.column_name}`;
+      const trimmed = r.description.trim();
+      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]
+    )) as TableCommentRow[];
+    const tableComments = new Map<string, string>();
+    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);
+    });
 
     // Primary key columns query
     const qbPk = new SelectQueryBuilder(PgKeyColumnUsage)
@@ -303,13 +332,14 @@ export const postgresIntrospector: SchemaIntrospector = {
         return;
       }
       if (!tablesByKey.has(key)) {
-        tablesByKey.set(key, {
-          name: r.table_name,
-          schema: r.table_schema,
-          columns: [],
-          primaryKey: pkMap.get(key) || [],
-          indexes: []
-        });
+        tablesByKey.set(key, {
+          name: r.table_name,
+          schema: r.table_schema,
+          columns: [],
+          primaryKey: pkMap.get(key) || [],
+          indexes: [],
+          comment: tableComments.get(key)
+        });
       }
       const cols = tablesByKey.get(key)!;
       const commentKey = `${r.table_schema}.${r.table_name}.${r.column_name}`;

package/src/core/ddl/introspect/sqlite.ts

@@ -1,6 +1,6 @@
 import { SchemaIntrospector, IntrospectOptions } from './types.js';
-import { shouldIncludeTable } from './utils.js';
-import { DatabaseSchema, DatabaseTable, DatabaseIndex } from '../schema-types.js';
+import { shouldIncludeTable, queryRows } from './utils.js';
+import { DatabaseSchema, DatabaseTable, DatabaseIndex, DatabaseColumn } from '../schema-types.js';
 import type { IntrospectContext } from './context.js';
 import { runSelectNode } from './run-select.js';
 import type { SelectQueryNode, TableNode } from '../../ast/query.js';
@@ -89,6 +89,58 @@ const runPragma = async <T>(
   return (await runSelectNode<T>(query, ctx)) as T[];
 };
 
+const loadSqliteSchemaComments = async (ctx: IntrospectContext) => {
+  const tableComments = new Map<string, string>();
+  const columnComments = new Map<string, string>();
+  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
+  };
+};
+
 export const sqliteIntrospector: SchemaIntrospector = {
   async introspect(ctx: IntrospectContext, options: IntrospectOptions): Promise<DatabaseSchema> {
     const alias = 'sqlite_master';
@@ -103,6 +155,7 @@ export const sqliteIntrospector: SchemaIntrospector = {
       )
     };
 
+    const { tableComments, columnComments } = await loadSqliteSchemaComments(ctx);
     const tableRows = (await runSelectNode<SqliteTableRow>(tablesQuery, ctx)) as SqliteTableRow[];
     const tables: DatabaseTable[] = [];
 
@@ -134,16 +187,27 @@ export const sqliteIntrospector: SchemaIntrospector = {
         ctx
       );
 
-      const tableEntry: DatabaseTable = { name: tableName, columns: [], primaryKey: [], indexes: [] };
+      const tableEntry: DatabaseTable = {
+        name: tableName,
+        columns: [],
+        primaryKey: [],
+        indexes: [],
+        comment: tableComments.get(tableName)
+      };
 
       tableInfo.forEach(info => {
-        tableEntry.columns.push({
+        const column: DatabaseColumn = {
           name: info.name,
           type: info.type,
           notNull: info.notnull === 1,
           default: info.dflt_value ?? undefined,
           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);

package/src/index.ts

@@ -38,8 +38,10 @@ export * from './orm/execution-context.js';
 export * from './orm/hydration-context.js';
 export * from './orm/domain-event-bus.js';
 export * from './orm/runtime-types.js';
-export * from './orm/query-logger.js';
-export * from './decorators/index.js';
+export * from './orm/query-logger.js';
+export * from './orm/jsonify.js';
+export * from './orm/save-graph-types.js';
+export * from './decorators/index.js';
 
 // NEW: execution abstraction + helpers
 export * from './core/execution/db-executor.js';

package/src/orm/jsonify.ts

@@ -0,0 +1,27 @@
+export type JsonifyScalar<T> = T extends Date ? string : T;
+
+/**
+ * Shallow JSON-friendly mapping:
+ * - Date -> ISO string
+ * - Everything else unchanged
+ */
+export type Jsonify<T> = {
+  [K in keyof T]: JsonifyScalar<T[K]>;
+};
+
+/**
+ * Creates a shallow, JSON-friendly copy of an object by converting `Date` values to ISO strings.
+ * This intentionally does not deep-walk nested objects/relations.
+ */
+export const jsonify = <T extends object>(value: T): Jsonify<T> => {
+  const record = value as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+
+  for (const key of Object.keys(record)) {
+    const entry = record[key];
+    result[key] = entry instanceof Date ? entry.toISOString() : entry;
+  }
+
+  return result as Jsonify<T>;
+};
+

package/src/orm/orm-session.ts

@@ -27,9 +27,10 @@ import {
   RelationKey,
   TrackedEntity
 } from './runtime-types.js';
-import { executeHydrated } from './execute.js';
-import { runInTransaction } from './transaction-runner.js';
-import { saveGraphInternal, SaveGraphOptions } from './save-graph.js';
+import { executeHydrated } from './execute.js';
+import { runInTransaction } from './transaction-runner.js';
+import { saveGraphInternal, SaveGraphOptions } from './save-graph.js';
+import type { SaveGraphInputPayload } from './save-graph-types.js';
 
 /**
  * Interface for ORM interceptors that allow hooking into the flush lifecycle.
@@ -297,25 +298,30 @@ export class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Entit
     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<TCtor extends EntityConstructor<object>>(
-    entityClass: TCtor,
-    payload: Record<string, unknown>,
-    options?: SaveGraphOptions & { transactional?: boolean }
-  ): Promise<InstanceType<TCtor>> {
-    const { transactional = true, ...graphOptions } = options ?? {};
-    const execute = () => saveGraphInternal(this, entityClass, payload, graphOptions);
-    if (!transactional) {
-      return execute();
-    }
-    return this.transaction(() => execute());
-  }
+  /**
+   * 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<TCtor extends EntityConstructor<object>>(
+    entityClass: TCtor,
+    payload: SaveGraphInputPayload<InstanceType<TCtor>>,
+    options?: SaveGraphOptions & { transactional?: boolean }
+  ): Promise<InstanceType<TCtor>>;
+  async saveGraph<TCtor extends EntityConstructor<object>>(
+    entityClass: TCtor,
+    payload: Record<string, unknown>,
+    options?: SaveGraphOptions & { transactional?: boolean }
+  ): Promise<InstanceType<TCtor>> {
+    const { transactional = true, ...graphOptions } = options ?? {};
+    const execute = () => saveGraphInternal(this, entityClass, payload, graphOptions);
+    if (!transactional) {
+      return execute();
+    }
+    return this.transaction(() => execute());
+  }
 
   /**
    * Persists an entity (either inserts or updates).

package/src/orm/save-graph-types.ts

@@ -0,0 +1,57 @@
+import type {
+  BelongsToReference,
+  HasManyCollection,
+  HasOneReference,
+  ManyToManyCollection
+} from '../schema/types.js';
+
+type AnyId = number | string;
+type AnyFn = (...args: unknown[]) => unknown;
+
+type RelationWrapper =
+  | HasManyCollection<unknown>
+  | HasOneReference<unknown>
+  | BelongsToReference<unknown>
+  | ManyToManyCollection<unknown>;
+
+type FunctionKeys<T> = {
+  [K in keyof T & string]-?: T[K] extends AnyFn ? K : never;
+}[keyof T & string];
+
+type RelationKeys<T> = {
+  [K in keyof T & string]-?: NonNullable<T[K]> extends RelationWrapper ? K : never;
+}[keyof T & string];
+
+type ColumnKeys<T> = Exclude<keyof T & string, FunctionKeys<T> | RelationKeys<T>>;
+
+export type SaveGraphJsonScalar<T> = T extends Date ? string : T;
+
+/**
+ * Input scalar type that accepts JSON-friendly values for common runtime types.
+ * Currently:
+ * - Date fields accept `Date | string` (ISO string recommended)
+ */
+export type SaveGraphInputScalar<T> =
+  T extends Date ? Date | string : T;
+
+type ColumnInput<TEntity> = {
+  [K in ColumnKeys<TEntity>]?: SaveGraphInputScalar<TEntity[K]>;
+};
+
+type RelationInputValue<T> =
+  T extends HasManyCollection<infer C> ? Array<SaveGraphInputPayload<C> | AnyId> :
+  T extends HasOneReference<infer C> ? SaveGraphInputPayload<C> | AnyId | null :
+  T extends BelongsToReference<infer P> ? SaveGraphInputPayload<P> | AnyId | null :
+  T extends ManyToManyCollection<infer Tgt> ? Array<SaveGraphInputPayload<Tgt> | AnyId> :
+  never;
+
+type RelationInput<TEntity> = {
+  [K in RelationKeys<TEntity>]?: RelationInputValue<NonNullable<TEntity[K]>>;
+};
+
+/**
+ * Typed payload accepted by `OrmSession.saveGraph`:
+ * - Only entity scalar keys + relation keys are accepted.
+ * - Scalars can use JSON-friendly values (e.g., Date fields accept ISO strings).
+ */
+export type SaveGraphInputPayload<TEntity> = ColumnInput<TEntity> & RelationInput<TEntity>;