metal-orm 1.0.50 → 1.0.52

package/dist/index.d.cts

@@ -92,6 +92,10 @@ declare const col: {
      * @returns ColumnDef with VARCHAR type
      */
     varchar: (length: number) => ColumnDef<"VARCHAR">;
+    /**
+     * Creates a text column definition
+     */
+    text: () => ColumnDef<"TEXT">;
     /**
      * Creates a fixed precision decimal column definition
      */
@@ -2985,8 +2989,45 @@ interface HydrationContext<E extends DomainEvent = AnyDomainEvent> {
 interface SaveGraphOptions {
     /** Remove existing collection members that are not present in the payload */
     pruneMissing?: boolean;
+    /**
+     * Coerce JSON-friendly input values into DB-friendly primitives.
+     * Currently:
+     * - Date -> ISO string (for DATE/DATETIME/TIMESTAMP/TIMESTAMPTZ columns)
+     */
+    coerce?: 'json';
 }
 
+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>>;
+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)
+ */
+type SaveGraphInputScalar<T> = T extends Date ? Date | string : T;
+type ColumnInput$1<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).
+ */
+type SaveGraphInputPayload<TEntity> = ColumnInput$1<TEntity> & RelationInput<TEntity>;
+
 /**
  * Interface for ORM interceptors that allow hooking into the flush lifecycle.
  */
@@ -3155,7 +3196,7 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
      * @param options - Graph save options
      * @returns The root entity instance
      */
-    saveGraph<TCtor extends EntityConstructor<object>>(entityClass: TCtor, payload: Record<string, unknown>, options?: SaveGraphOptions & {
+    saveGraph<TCtor extends EntityConstructor<object>>(entityClass: TCtor, payload: SaveGraphInputPayload<InstanceType<TCtor>>, options?: SaveGraphOptions & {
         transactional?: boolean;
     }): Promise<InstanceType<TCtor>>;
     /**
@@ -5250,6 +5291,21 @@ declare function executeHydrated<TTable extends TableDef>(session: OrmSession, q
  */
 declare function executeHydratedWithContexts<TTable extends TableDef>(_execCtx: ExecutionContext, hydCtx: HydrationContext, qb: SelectQueryBuilder<unknown, TTable>): Promise<EntityInstance<TTable>[]>;
 
+type JsonifyScalar<T> = T extends Date ? string : T;
+/**
+ * Shallow JSON-friendly mapping:
+ * - Date -> ISO string
+ * - Everything else unchanged
+ */
+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.
+ */
+declare const jsonify: <T extends object>(value: T) => Jsonify<T>;
+
 /**
  * Context object provided by standard decorators in newer TypeScript versions.
  */
@@ -5549,4 +5605,4 @@ type PooledExecutorFactoryOptions<TConn> = {
  */
 declare function createPooledExecutorFactory<TConn>(opts: PooledExecutorFactoryOptions<TConn>): DbExecutorFactory;
 
-export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, aliasRef, and, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bootstrapEntities, caseWhen, cast, ceil, ceiling, char, charLength, clearExpressionDispatchers, clearOperandDispatchers, col, columnOperand, concat, concatWs, correlateBy, cos, cot, count, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedWithContexts, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, getColumn, getSchemaIntrospector, getTableDefFromEntity, groupConcat, gt, gte, hasMany, hasOne, hydrateRows, inList, inSubquery, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonPath, lag, lastValue, lead, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, locate, log, log10, logBase, lower, lpad, lt, lte, ltrim, max, min, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, or, outerRef, pi, position, pow, power, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, renderColumnDefinition, renderTypeWithArgs, repeat, replace, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, sel, selectFromEntity, sign, sin, space, sqrt, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, visitExpression, visitOperand, weekOfYear, windowFunction, year };
+export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, aliasRef, and, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bootstrapEntities, caseWhen, cast, ceil, ceiling, char, charLength, clearExpressionDispatchers, clearOperandDispatchers, col, columnOperand, concat, concatWs, correlateBy, cos, cot, count, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedWithContexts, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, getColumn, getSchemaIntrospector, getTableDefFromEntity, groupConcat, gt, gte, hasMany, hasOne, hydrateRows, inList, inSubquery, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonPath, jsonify, lag, lastValue, lead, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, locate, log, log10, logBase, lower, lpad, lt, lte, ltrim, max, min, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, or, outerRef, pi, position, pow, power, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, renderColumnDefinition, renderTypeWithArgs, repeat, replace, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, sel, selectFromEntity, sign, sin, space, sqrt, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, visitExpression, visitOperand, weekOfYear, windowFunction, year };

package/dist/index.d.ts

@@ -92,6 +92,10 @@ declare const col: {
      * @returns ColumnDef with VARCHAR type
      */
     varchar: (length: number) => ColumnDef<"VARCHAR">;
+    /**
+     * Creates a text column definition
+     */
+    text: () => ColumnDef<"TEXT">;
     /**
      * Creates a fixed precision decimal column definition
      */
@@ -2985,8 +2989,45 @@ interface HydrationContext<E extends DomainEvent = AnyDomainEvent> {
 interface SaveGraphOptions {
     /** Remove existing collection members that are not present in the payload */
     pruneMissing?: boolean;
+    /**
+     * Coerce JSON-friendly input values into DB-friendly primitives.
+     * Currently:
+     * - Date -> ISO string (for DATE/DATETIME/TIMESTAMP/TIMESTAMPTZ columns)
+     */
+    coerce?: 'json';
 }
 
+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>>;
+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)
+ */
+type SaveGraphInputScalar<T> = T extends Date ? Date | string : T;
+type ColumnInput$1<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).
+ */
+type SaveGraphInputPayload<TEntity> = ColumnInput$1<TEntity> & RelationInput<TEntity>;
+
 /**
  * Interface for ORM interceptors that allow hooking into the flush lifecycle.
  */
@@ -3155,7 +3196,7 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
      * @param options - Graph save options
      * @returns The root entity instance
      */
-    saveGraph<TCtor extends EntityConstructor<object>>(entityClass: TCtor, payload: Record<string, unknown>, options?: SaveGraphOptions & {
+    saveGraph<TCtor extends EntityConstructor<object>>(entityClass: TCtor, payload: SaveGraphInputPayload<InstanceType<TCtor>>, options?: SaveGraphOptions & {
         transactional?: boolean;
     }): Promise<InstanceType<TCtor>>;
     /**
@@ -5250,6 +5291,21 @@ declare function executeHydrated<TTable extends TableDef>(session: OrmSession, q
  */
 declare function executeHydratedWithContexts<TTable extends TableDef>(_execCtx: ExecutionContext, hydCtx: HydrationContext, qb: SelectQueryBuilder<unknown, TTable>): Promise<EntityInstance<TTable>[]>;
 
+type JsonifyScalar<T> = T extends Date ? string : T;
+/**
+ * Shallow JSON-friendly mapping:
+ * - Date -> ISO string
+ * - Everything else unchanged
+ */
+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.
+ */
+declare const jsonify: <T extends object>(value: T) => Jsonify<T>;
+
 /**
  * Context object provided by standard decorators in newer TypeScript versions.
  */
@@ -5549,4 +5605,4 @@ type PooledExecutorFactoryOptions<TConn> = {
  */
 declare function createPooledExecutorFactory<TConn>(opts: PooledExecutorFactoryOptions<TConn>): DbExecutorFactory;
 
-export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, aliasRef, and, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bootstrapEntities, caseWhen, cast, ceil, ceiling, char, charLength, clearExpressionDispatchers, clearOperandDispatchers, col, columnOperand, concat, concatWs, correlateBy, cos, cot, count, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedWithContexts, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, getColumn, getSchemaIntrospector, getTableDefFromEntity, groupConcat, gt, gte, hasMany, hasOne, hydrateRows, inList, inSubquery, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonPath, lag, lastValue, lead, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, locate, log, log10, logBase, lower, lpad, lt, lte, ltrim, max, min, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, or, outerRef, pi, position, pow, power, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, renderColumnDefinition, renderTypeWithArgs, repeat, replace, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, sel, selectFromEntity, sign, sin, space, sqrt, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, visitExpression, visitOperand, weekOfYear, windowFunction, year };
+export { type AliasRefNode, type AnyDomainEvent, type ArithmeticExpressionNode, type TableRef as AstTableRef, AsyncLocalStorage, BelongsTo, BelongsToMany, type BelongsToManyOptions, type BelongsToManyRelation, type BelongsToOptions, type BelongsToReference, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, DefaultBelongsToReference, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityOptions, EntityStatus, type ExecutionContext, type ExistsExpressionNode, type ExpressionNode, type ExpressionVisitor, type ForeignKeyReference, type FunctionNode, type GroupConcatOptions, type HasDomainEvents, HasMany, type HasManyCollection, type HasManyOptions, type HasManyRelation, HasOne, type HasOneOptions, type HasOneReference, type HasOneRelation, type HydrationContext, type HydrationMetadata, type HydrationPivotPlan, type HydrationPlan, type HydrationRelationPlan, type InExpressionNode, type InExpressionRight, type IndexColumn, type IndexDef, type InferRow, type InitialHandlers, InsertQueryBuilder, type IntrospectOptions, type JsonPathNode, type Jsonify, type JsonifyScalar, type LiteralNode, type LiteralValue, type LogicalExpressionNode, type ManyToManyCollection, type MssqlClientLike, MySqlDialect, type MysqlClientLike, type NullExpressionNode, type OperandNode, type OperandVisitor, Orm, type OrmDomainEvent, type OrmInterceptor, type OrmOptions, OrmSession, type OrmSessionOptions, Pool, type PoolAdapter, type PoolLease, type PoolOptions, type PooledConnectionAdapter, type PostgresClientLike, PostgresDialect, PrimaryKey, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SimpleQueryRunner, SqlServerDialect, type SqliteClientLike, SqliteDialect, type StandardColumnType, type SynchronizeOptions, type TableDef, type TableHooks, type TableOptions, type TableRef$1 as TableRef, type TediousColumn, type TediousConnectionLike, type TediousModule, type TediousRequest, type TediousRequestCtor, type TediousTypes, type TrackedEntity, TypeScriptGenerator, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, aliasRef, and, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bootstrapEntities, caseWhen, cast, ceil, ceiling, char, charLength, clearExpressionDispatchers, clearOperandDispatchers, col, columnOperand, concat, concatWs, correlateBy, cos, cot, count, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedWithContexts, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, getColumn, getSchemaIntrospector, getTableDefFromEntity, groupConcat, gt, gte, hasMany, hasOne, hydrateRows, inList, inSubquery, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonPath, jsonify, lag, lastValue, lead, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, locate, log, log10, logBase, lower, lpad, lt, lte, ltrim, max, min, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, or, outerRef, pi, position, pow, power, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, renderColumnDefinition, renderTypeWithArgs, repeat, replace, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, sel, selectFromEntity, sign, sin, space, sqrt, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, upper, utcNow, valueToOperand, visitExpression, visitOperand, weekOfYear, windowFunction, year };

package/dist/index.js

@@ -159,6 +159,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
    */
@@ -6667,6 +6671,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,
@@ -6807,7 +6834,8 @@ var postgresIntrospector = {
           schema: r.table_schema,
           columns: [],
           primaryKey: pkMap.get(key) || [],
-          indexes: []
+          indexes: [],
+          comment: tableComments.get(key)
         });
       }
       const cols = tablesByKey.get(key);
@@ -7192,6 +7220,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";
@@ -7205,6 +7280,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) {
@@ -7231,15 +7307,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);
@@ -7511,6 +7598,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" },
@@ -7816,7 +7957,8 @@ var mssqlIntrospector = {
           schema: r.table_schema,
           columns: [],
           primaryKey: pkMap.get(key) || [],
-          indexes: []
+          indexes: [],
+          comment: tableComments.get(key)
         });
       }
       const table = tablesByKey.get(key);
@@ -7827,6 +7969,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 = {
@@ -9155,18 +9301,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);
@@ -9179,10 +9337,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);
     }
   }
 };
@@ -9209,8 +9367,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);
@@ -9285,8 +9443,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);
@@ -9317,7 +9475,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);
@@ -9328,7 +9486,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;
 };
@@ -9511,13 +9669,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);
@@ -9718,6 +9869,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) => {
@@ -10601,6 +10763,7 @@ export {
   isValueOperandInput,
   isWindowFunctionNode,
   jsonPath,
+  jsonify,
   lag,
   lastValue,
   lead,