metal-orm 1.0.66 → 1.0.68

package/dist/index.d.cts

@@ -653,8 +653,8 @@ interface TableRef {
  */
 interface LiteralNode {
     type: 'Literal';
-    /** The literal value (string, number, boolean, or null) */
-    value: string | number | boolean | null;
+    /** The literal value (string, number, boolean, Date, or null) */
+    value: string | number | boolean | Date | null;
 }
 /**
  * AST node representing a reference to a SELECT alias (for ORDER BY / GROUP BY).
@@ -3466,9 +3466,10 @@ interface SaveGraphOptions {
     /**
      * Coerce JSON-friendly input values into DB-friendly primitives.
      * Currently:
-     * - Date -> ISO string (for DATE/DATETIME/TIMESTAMP/TIMESTAMPTZ columns)
+     * - `json`: Date -> ISO string (for DATE/DATETIME/TIMESTAMP/TIMESTAMPTZ columns)
+     * - `json-in`: string/number -> Date (for DATE/DATETIME/TIMESTAMP/TIMESTAMPTZ columns)
      */
-    coerce?: 'json';
+    coerce?: 'json' | 'json-in';
 }
 
 type AnyId = number | string;
@@ -3486,8 +3487,9 @@ type SaveGraphJsonScalar<T> = T extends Date ? string : T;
  * Input scalar type for `OrmSession.saveGraph` payloads.
  *
  * Note: runtime coercion is opt-in via `SaveGraphOptions.coerce`.
+ * For Date columns, string input is only safe when using `coerce: 'json-in'`.
  */
-type SaveGraphInputScalar<T> = T;
+type SaveGraphInputScalar<T> = T extends Date ? T | string | number : T;
 type ColumnInput$1<TEntity> = {
     [K in ColumnKeys<TEntity>]?: SaveGraphInputScalar<TEntity[K]>;
 };
@@ -3532,6 +3534,12 @@ interface OrmSessionOptions<E extends DomainEvent = OrmDomainEvent> {
     /** Optional domain event handlers */
     domainEventHandlers?: InitialHandlers<E, OrmSession<E>>;
 }
+interface SaveGraphSessionOptions extends SaveGraphOptions {
+    /** Wrap the save operation in a transaction (default: true). */
+    transactional?: boolean;
+    /** Flush after saveGraph when not transactional (default: false). */
+    flush?: boolean;
+}
 /**
  * ORM Session that manages entity lifecycle, identity mapping, and database operations.
  * @template E - The domain event type
@@ -3550,6 +3558,7 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
     /** The relation change processor */
     readonly relationChanges: RelationChangeProcessor;
     private readonly interceptors;
+    private saveGraphDefaults?;
     /**
      * Creates a new OrmSession instance.
      * @param opts - Session options
@@ -3639,6 +3648,12 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
     registerDomainEventHandler<TType extends E['type']>(type: TType, handler: DomainEventHandler<Extract<E, {
         type: TType;
     }>, OrmSession<E>>): void;
+    /**
+     * Sets default options applied to all saveGraph calls for this session.
+     * Per-call options override these defaults.
+     * @param defaults - Default saveGraph options for the session
+     */
+    withSaveGraphDefaults(defaults: SaveGraphSessionOptions): this;
     /**
      * Finds an entity by its primary key.
      * @template TCtor - The entity constructor type
@@ -3669,9 +3684,23 @@ 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: SaveGraphInputPayload<InstanceType<TCtor>>, options?: SaveGraphOptions & {
-        transactional?: boolean;
-    }): Promise<InstanceType<TCtor>>;
+    saveGraph<TCtor extends EntityConstructor<object>>(entityClass: TCtor, payload: SaveGraphInputPayload<InstanceType<TCtor>>, options?: SaveGraphSessionOptions): Promise<InstanceType<TCtor>>;
+    /**
+     * Saves an entity graph and flushes immediately (defaults to transactional: false).
+     * @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
+     */
+    saveGraphAndFlush<TCtor extends EntityConstructor<object>>(entityClass: TCtor, payload: SaveGraphInputPayload<InstanceType<TCtor>>, options?: SaveGraphSessionOptions): Promise<InstanceType<TCtor>>;
+    /**
+     * Updates an existing entity graph (requires a primary key in the 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 or null if not found
+     */
+    updateGraph<TCtor extends EntityConstructor<object>>(entityClass: TCtor, payload: SaveGraphInputPayload<InstanceType<TCtor>>, options?: SaveGraphSessionOptions): Promise<InstanceType<TCtor> | null>;
     /**
      * Persists an entity (either inserts or updates).
      * @param entity - The entity to persist
@@ -3717,6 +3746,12 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
      * @returns The hydration context
      */
     getHydrationContext(): HydrationContext<E>;
+    /**
+     * Merges session defaults with per-call saveGraph options.
+     * @param options - Per-call saveGraph options
+     * @returns Combined options with per-call values taking precedence
+     */
+    private resolveSaveGraphOptions;
 }
 
 type WhereHasOptions = {
@@ -6948,4 +6983,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 BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, ConstructorMaterializationStrategy, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, type DecoratedEntityInstance, DefaultBelongsToReference, DefaultEntityMaterializer, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityMaterializationStrategy, type EntityMaterializer, type EntityOptions, type PrimaryKey$1 as EntityPrimaryKey, 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 HasOneReferenceApi, 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 Primitive, PrototypeMaterializationStrategy, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as 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 SelectableKeys, 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, type TypedExpression, type TypedLike, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, asType, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, deleteFrom, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedPlain, executeHydratedPlainWithContexts, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, insertInto, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, materializeAs, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFrom, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, update, upper, utcNow, valueToOperand, variance, 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 BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, ConstructorMaterializationStrategy, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, type DecoratedEntityInstance, DefaultBelongsToReference, DefaultEntityMaterializer, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityMaterializationStrategy, type EntityMaterializer, type EntityOptions, type PrimaryKey$1 as EntityPrimaryKey, 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 HasOneReferenceApi, 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 Primitive, PrototypeMaterializationStrategy, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type SaveGraphSessionOptions, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SelectableKeys, 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, type TypedExpression, type TypedLike, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, asType, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, deleteFrom, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedPlain, executeHydratedPlainWithContexts, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, insertInto, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, materializeAs, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFrom, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, update, upper, utcNow, valueToOperand, variance, visitExpression, visitOperand, weekOfYear, windowFunction, year };

package/dist/index.d.ts

@@ -653,8 +653,8 @@ interface TableRef {
  */
 interface LiteralNode {
     type: 'Literal';
-    /** The literal value (string, number, boolean, or null) */
-    value: string | number | boolean | null;
+    /** The literal value (string, number, boolean, Date, or null) */
+    value: string | number | boolean | Date | null;
 }
 /**
  * AST node representing a reference to a SELECT alias (for ORDER BY / GROUP BY).
@@ -3466,9 +3466,10 @@ interface SaveGraphOptions {
     /**
      * Coerce JSON-friendly input values into DB-friendly primitives.
      * Currently:
-     * - Date -> ISO string (for DATE/DATETIME/TIMESTAMP/TIMESTAMPTZ columns)
+     * - `json`: Date -> ISO string (for DATE/DATETIME/TIMESTAMP/TIMESTAMPTZ columns)
+     * - `json-in`: string/number -> Date (for DATE/DATETIME/TIMESTAMP/TIMESTAMPTZ columns)
      */
-    coerce?: 'json';
+    coerce?: 'json' | 'json-in';
 }
 
 type AnyId = number | string;
@@ -3486,8 +3487,9 @@ type SaveGraphJsonScalar<T> = T extends Date ? string : T;
  * Input scalar type for `OrmSession.saveGraph` payloads.
  *
  * Note: runtime coercion is opt-in via `SaveGraphOptions.coerce`.
+ * For Date columns, string input is only safe when using `coerce: 'json-in'`.
  */
-type SaveGraphInputScalar<T> = T;
+type SaveGraphInputScalar<T> = T extends Date ? T | string | number : T;
 type ColumnInput$1<TEntity> = {
     [K in ColumnKeys<TEntity>]?: SaveGraphInputScalar<TEntity[K]>;
 };
@@ -3532,6 +3534,12 @@ interface OrmSessionOptions<E extends DomainEvent = OrmDomainEvent> {
     /** Optional domain event handlers */
     domainEventHandlers?: InitialHandlers<E, OrmSession<E>>;
 }
+interface SaveGraphSessionOptions extends SaveGraphOptions {
+    /** Wrap the save operation in a transaction (default: true). */
+    transactional?: boolean;
+    /** Flush after saveGraph when not transactional (default: false). */
+    flush?: boolean;
+}
 /**
  * ORM Session that manages entity lifecycle, identity mapping, and database operations.
  * @template E - The domain event type
@@ -3550,6 +3558,7 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
     /** The relation change processor */
     readonly relationChanges: RelationChangeProcessor;
     private readonly interceptors;
+    private saveGraphDefaults?;
     /**
      * Creates a new OrmSession instance.
      * @param opts - Session options
@@ -3639,6 +3648,12 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
     registerDomainEventHandler<TType extends E['type']>(type: TType, handler: DomainEventHandler<Extract<E, {
         type: TType;
     }>, OrmSession<E>>): void;
+    /**
+     * Sets default options applied to all saveGraph calls for this session.
+     * Per-call options override these defaults.
+     * @param defaults - Default saveGraph options for the session
+     */
+    withSaveGraphDefaults(defaults: SaveGraphSessionOptions): this;
     /**
      * Finds an entity by its primary key.
      * @template TCtor - The entity constructor type
@@ -3669,9 +3684,23 @@ 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: SaveGraphInputPayload<InstanceType<TCtor>>, options?: SaveGraphOptions & {
-        transactional?: boolean;
-    }): Promise<InstanceType<TCtor>>;
+    saveGraph<TCtor extends EntityConstructor<object>>(entityClass: TCtor, payload: SaveGraphInputPayload<InstanceType<TCtor>>, options?: SaveGraphSessionOptions): Promise<InstanceType<TCtor>>;
+    /**
+     * Saves an entity graph and flushes immediately (defaults to transactional: false).
+     * @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
+     */
+    saveGraphAndFlush<TCtor extends EntityConstructor<object>>(entityClass: TCtor, payload: SaveGraphInputPayload<InstanceType<TCtor>>, options?: SaveGraphSessionOptions): Promise<InstanceType<TCtor>>;
+    /**
+     * Updates an existing entity graph (requires a primary key in the 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 or null if not found
+     */
+    updateGraph<TCtor extends EntityConstructor<object>>(entityClass: TCtor, payload: SaveGraphInputPayload<InstanceType<TCtor>>, options?: SaveGraphSessionOptions): Promise<InstanceType<TCtor> | null>;
     /**
      * Persists an entity (either inserts or updates).
      * @param entity - The entity to persist
@@ -3717,6 +3746,12 @@ declare class OrmSession<E extends DomainEvent = OrmDomainEvent> implements Enti
      * @returns The hydration context
      */
     getHydrationContext(): HydrationContext<E>;
+    /**
+     * Merges session defaults with per-call saveGraph options.
+     * @param options - Per-call saveGraph options
+     * @returns Combined options with per-call values taking precedence
+     */
+    private resolveSaveGraphOptions;
 }
 
 type WhereHasOptions = {
@@ -6948,4 +6983,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 BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, ConstructorMaterializationStrategy, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, type DecoratedEntityInstance, DefaultBelongsToReference, DefaultEntityMaterializer, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityMaterializationStrategy, type EntityMaterializer, type EntityOptions, type PrimaryKey$1 as EntityPrimaryKey, 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 HasOneReferenceApi, 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 Primitive, PrototypeMaterializationStrategy, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as 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 SelectableKeys, 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, type TypedExpression, type TypedLike, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, asType, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, deleteFrom, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedPlain, executeHydratedPlainWithContexts, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, insertInto, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, materializeAs, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFrom, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, update, upper, utcNow, valueToOperand, variance, 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 BelongsToReferenceApi, type BelongsToRelation, type BetweenExpressionNode, type BinaryExpressionNode, type BitwiseExpressionNode, type CascadeMode, type CaseExpressionNode, type CastExpressionNode, type CheckConstraint, type CollateExpressionNode, Column, type ColumnDef, type ColumnDiff, type ColumnInput, type ColumnNode, type ColumnOptions, type ColumnRef, type ColumnToTs, type ColumnType, ConstructorMaterializationStrategy, type CreateTediousClientOptions, type DatabaseCheck, type DatabaseColumn, type DatabaseIndex, type DatabaseSchema, type DatabaseTable, type DbExecutor, type DbExecutorFactory, type DecoratedEntityInstance, DefaultBelongsToReference, DefaultEntityMaterializer, DefaultHasManyCollection, DefaultManyToManyCollection, type DefaultValue, DeleteQueryBuilder, type DialectName, type DomainEvent, DomainEventBus, type DomainEventHandler, Entity, type EntityContext, type EntityInstance, type EntityMaterializationStrategy, type EntityMaterializer, type EntityOptions, type PrimaryKey$1 as EntityPrimaryKey, 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 HasOneReferenceApi, 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 Primitive, PrototypeMaterializationStrategy, type QueryLogEntry, type QueryLogger, type QueryResult, type RawDefaultValue, type ReferentialAction, type RelationChange, type RelationChangeEntry, type RelationDef, type RelationKey$1 as RelationKey, RelationKinds, type RelationMap, type RelationTargetTable, type RelationType, type RenderColumnOptions, STANDARD_COLUMN_TYPES, type SaveGraphInputPayload, type SaveGraphInputScalar, type SaveGraphJsonScalar, type SaveGraphSessionOptions, type ScalarSubqueryNode, type SchemaChange, type SchemaChangeKind, type SchemaDiffOptions, type SchemaGenerateResult, type SchemaIntrospector, type SchemaPlan, SelectQueryBuilder, type SelectQueryInput, type SelectableKeys, 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, type TypedExpression, type TypedLike, UpdateQueryBuilder, type ValueOperandInput, type WindowFunctionNode, abs, acos, add, addDomainEvent, age, aliasRef, and, arrayAppend, asType, ascii, asin, atan, atan2, avg, belongsTo, belongsToMany, between, bitAnd, bitLength, bitOr, bitXor, bootstrapEntities, caseWhen, cast, cbrt, ceil, ceiling, char, charLength, chr, clearExpressionDispatchers, clearOperandDispatchers, coalesce, col, collate, columnOperand, concat, concatWs, correlateBy, cos, cot, count, countAll, createEntityFromRow, createEntityProxy, createExecutorFromQueryRunner, createMssqlExecutor, createMysqlExecutor, createPooledExecutorFactory, createPostgresExecutor, createQueryLoggingExecutor, createSqliteExecutor, createTediousExecutor, createTediousMssqlClient, currentDate, currentTime, dateAdd, dateDiff, dateFormat, dateSub, dateTrunc, day, dayOfWeek, defineTable, degrees, deleteFrom, denseRank, diffSchema, div, endOfMonth, entityRef, eq, esel, executeHydrated, executeHydratedPlain, executeHydratedPlainWithContexts, executeHydratedWithContexts, executeSchemaSql, executeSchemaSqlFor, exists, exp, extract, firstValue, floor, fromUnixTime, generateCreateTableSql, generateSchemaSql, generateSchemaSqlFor, getColumn, getDecoratorMetadata, getSchemaIntrospector, getTableDefFromEntity, greatest, groupConcat, gt, gte, hasMany, hasOne, hour, hydrateRows, ifNull, inList, inSubquery, initcap, insertInto, instr, introspectSchema, isCaseExpressionNode, isCastExpressionNode, isCollateExpressionNode, isExpressionSelectionNode, isFunctionNode, isNotNull, isNull, isOperandNode, isValueOperandInput, isWindowFunctionNode, jsonArrayAgg, jsonContains, jsonLength, jsonPath, jsonSet, jsonify, lag, lastValue, lead, least, left, length, like, ln, loadBelongsToManyRelation, loadBelongsToRelation, loadHasManyRelation, loadHasOneRelation, localTime, localTimestamp, locate, log, log10, log2, logBase, lower, lpad, lt, lte, ltrim, materializeAs, max, md5, min, minute, mod, month, mul, neq, normalizeColumnType, notBetween, notExists, notInList, notInSubquery, notLike, now, ntile, nullif, octetLength, or, outerRef, pi, position, pow, power, quarter, radians, rand, random, rank, registerExpressionDispatcher, registerOperandDispatcher, registerSchemaIntrospector, relationLoaderCache, renderColumnDefinition, renderTypeWithArgs, repeat, replace, reverse, right, round, rowNumber, rowsToQueryResult, rpad, rtrim, second, sel, selectFrom, selectFromEntity, setRelations, sha1, sha2, shiftLeft, shiftRight, sign, sin, space, sqrt, stddev, sub, substr, sum, synchronizeSchema, tableRef, tan, toColumnRef, toTableRef, trim, trunc, truncate, unixTimestamp, update, upper, utcNow, valueToOperand, variance, visitExpression, visitOperand, weekOfYear, windowFunction, year };

package/dist/index.js

@@ -383,10 +383,10 @@ var isWindowFunctionNode = (node) => isOperandNode(node) && node.type === "Windo
 var isExpressionSelectionNode = (node) => isFunctionNode(node) || isCaseExpressionNode(node) || isCastExpressionNode(node) || isWindowFunctionNode(node);
 
 // src/core/ast/expression-builders.ts
-var isLiteralValue = (value) => value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+var isLiteralValue = (value) => value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value instanceof Date;
 var toLiteralNode = (value) => ({
   type: "Literal",
-  value
+  value: value instanceof Date ? value.toISOString() : value
 });
 var columnRefToNode = (col2) => {
   if (!col2.table) {
@@ -11449,14 +11449,28 @@ var runInTransaction = async (executor, action) => {
 // src/orm/save-graph.ts
 var toKey8 = (value) => value === null || value === void 0 ? "" : String(value);
 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();
+  if (!isDateLikeColumn) return value;
+  if (options.coerce === "json") {
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    return value;
+  }
+  if (options.coerce === "json-in") {
+    if (value instanceof Date) return value;
+    if (typeof value === "string" || typeof value === "number") {
+      const date = new Date(value);
+      if (Number.isNaN(date.getTime())) {
+        throw new Error(`Invalid date value for column "${columnName}"`);
+      }
+      return date;
+    }
+    return value;
   }
   return value;
 };
@@ -11653,6 +11667,7 @@ var OrmSession = class {
   /** The relation change processor */
   relationChanges;
   interceptors;
+  saveGraphDefaults;
   /**
    * Creates a new OrmSession instance.
    * @param opts - Session options
@@ -11783,6 +11798,15 @@ var OrmSession = class {
   registerDomainEventHandler(type, handler) {
     this.domainEvents.on(type, handler);
   }
+  /**
+   * Sets default options applied to all saveGraph calls for this session.
+   * Per-call options override these defaults.
+   * @param defaults - Default saveGraph options for the session
+   */
+  withSaveGraphDefaults(defaults) {
+    this.saveGraphDefaults = { ...defaults };
+    return this;
+  }
   /**
    * Finds an entity by its primary key.
    * @template TCtor - The entity constructor type
@@ -11830,10 +11854,60 @@ var OrmSession = class {
     return executeHydrated(this, qb);
   }
   async saveGraph(entityClass, payload, options) {
-    const { transactional = true, ...graphOptions } = options ?? {};
+    const resolved = this.resolveSaveGraphOptions(options);
+    const { transactional = true, flush = false, ...graphOptions } = resolved;
     const execute = () => saveGraphInternal(this, entityClass, payload, graphOptions);
     if (!transactional) {
-      return execute();
+      const result = await execute();
+      if (flush) {
+        await this.flush();
+      }
+      return result;
+    }
+    return this.transaction(() => execute());
+  }
+  /**
+   * Saves an entity graph and flushes immediately (defaults to transactional: false).
+   * @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 saveGraphAndFlush(entityClass, payload, options) {
+    const merged = { ...options ?? {}, flush: true, transactional: options?.transactional ?? false };
+    return this.saveGraph(entityClass, payload, merged);
+  }
+  /**
+   * Updates an existing entity graph (requires a primary key in the 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 or null if not found
+   */
+  async updateGraph(entityClass, payload, options) {
+    const table = getTableDefFromEntity(entityClass);
+    if (!table) {
+      throw new Error("Entity metadata has not been bootstrapped");
+    }
+    const primaryKey = findPrimaryKey(table);
+    const pkValue = payload[primaryKey];
+    if (pkValue === void 0 || pkValue === null) {
+      throw new Error(`updateGraph requires a primary key value for "${primaryKey}"`);
+    }
+    const resolved = this.resolveSaveGraphOptions(options);
+    const { transactional = true, flush = false, ...graphOptions } = resolved;
+    const execute = async () => {
+      const tracked = this.getEntity(table, pkValue);
+      const existing = tracked ?? await this.find(entityClass, pkValue);
+      if (!existing) return null;
+      return saveGraphInternal(this, entityClass, payload, graphOptions);
+    };
+    if (!transactional) {
+      const result = await execute();
+      if (result && flush) {
+        await this.flush();
+      }
+      return result;
     }
     return this.transaction(() => execute());
   }
@@ -11953,6 +12027,14 @@ var OrmSession = class {
       entityContext: this
     };
   }
+  /**
+   * Merges session defaults with per-call saveGraph options.
+   * @param options - Per-call saveGraph options
+   * @returns Combined options with per-call values taking precedence
+   */
+  resolveSaveGraphOptions(options) {
+    return { ...this.saveGraphDefaults ?? {}, ...options ?? {} };
+  }
 };
 var buildRelationChangeEntry = (root, relationKey, rootTable, relationName, relation, change) => ({
   root,