metal-orm 1.0.51 → 1.0.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.51",
+  "version": "1.0.52",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {

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

package/src/orm/save-graph.ts

@@ -1,15 +1,16 @@
-import type {
-  EntityInstance,
-  HasManyCollection,
-  HasOneReference,
-  BelongsToReference,
-  ManyToManyCollection
-} from '../schema/types.js';
-import {
-  RelationKinds,
-  type BelongsToManyRelation,
-  type BelongsToRelation,
-  type HasManyRelation,
+import type {
+  EntityInstance,
+  HasManyCollection,
+  HasOneReference,
+  BelongsToReference,
+  ManyToManyCollection
+} from '../schema/types.js';
+import { normalizeColumnType, type ColumnDef } from '../schema/column-types.js';
+import {
+  RelationKinds,
+  type BelongsToManyRelation,
+  type BelongsToRelation,
+  type HasManyRelation,
   type HasOneRelation,
   type RelationDef
 } from '../schema/relation.js';
@@ -23,10 +24,16 @@ import type { OrmSession } from './orm-session.js';
 /**
  * Options for controlling the behavior of save graph operations.
  */
-export interface SaveGraphOptions {
-  /** Remove existing collection members that are not present in the payload */
-  pruneMissing?: boolean;
-}
+export 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';
+}
 
 /** Represents an entity object with arbitrary properties. */
 
@@ -44,26 +51,55 @@ type AnyEntity = Record<string, unknown>;
 
  */
 
-const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
-
-const pickColumns = (table: TableDef, payload: AnyEntity): Record<string, unknown> => {
-  const columns: Record<string, unknown> = {};
-  for (const key of Object.keys(table.columns)) {
-    if (payload[key] !== undefined) {
-      columns[key] = payload[key];
-    }
-  }
-  return columns;
-};
-
-const ensureEntity = <TTable extends TableDef>(
-  session: OrmSession,
-  table: TTable,
-  payload: AnyEntity
-): EntityInstance<TTable> => {
-  const pk = findPrimaryKey(table);
-  const row = pickColumns(table, payload);
-  const pkValue = payload[pk];
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+const coerceColumnValue = (
+  table: TableDef,
+  columnName: string,
+  value: unknown,
+  options: SaveGraphOptions
+): unknown => {
+  if (options.coerce !== 'json') return value;
+  if (value === null || value === undefined) return value;
+
+  const column = table.columns[columnName] as unknown as ColumnDef | undefined;
+  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();
+  }
+
+  // Future coercions can be added here based on `normalized`.
+  return value;
+};
+
+const pickColumns = (table: TableDef, payload: AnyEntity, options: SaveGraphOptions): Record<string, unknown> => {
+  const columns: Record<string, unknown> = {};
+  for (const key of Object.keys(table.columns)) {
+    if (payload[key] !== undefined) {
+      columns[key] = coerceColumnValue(table, key, payload[key], options);
+    }
+  }
+  return columns;
+};
+
+const ensureEntity = <TTable extends TableDef>(
+  session: OrmSession,
+  table: TTable,
+  payload: AnyEntity,
+  options: SaveGraphOptions
+): EntityInstance<TTable> => {
+  const pk = findPrimaryKey(table);
+  const row = pickColumns(table, payload, options);
+  const pkValue = payload[pk];
 
   if (pkValue !== undefined && pkValue !== null) {
     const tracked = session.getEntity(table, pkValue);
@@ -76,16 +112,16 @@ const ensureEntity = <TTable extends TableDef>(
     }
   }
 
-  return createEntityFromRow(session, table, row) as EntityInstance<TTable>;
-};
-
-const assignColumns = (table: TableDef, entity: AnyEntity, payload: AnyEntity): void => {
-  for (const key of Object.keys(table.columns)) {
-    if (payload[key] !== undefined) {
-      entity[key] = payload[key];
-    }
-  }
-};
+  return createEntityFromRow(session, table, row) as EntityInstance<TTable>;
+};
+
+const assignColumns = (table: TableDef, entity: AnyEntity, payload: AnyEntity, options: SaveGraphOptions): void => {
+  for (const key of Object.keys(table.columns)) {
+    if (payload[key] !== undefined) {
+      entity[key] = coerceColumnValue(table, key, payload[key], options);
+    }
+  }
+};
 
 const isEntityInCollection = (items: AnyEntity[], pkName: string, entity: AnyEntity): boolean => {
   if (items.includes(entity)) return true;
@@ -121,13 +157,13 @@ const handleHasMany = async (
     const asObj = typeof item === 'object' ? (item as AnyEntity) : { [targetPk]: item };
     const pkValue = asObj[targetPk];
 
-    const current =
-      findInCollectionByPk(existing, targetPk, pkValue) ??
-      (pkValue !== undefined && pkValue !== null ? session.getEntity(targetTable, pkValue) : undefined);
-
-    const entity = current ?? ensureEntity(session, targetTable, asObj);
-    assignColumns(targetTable, entity as AnyEntity, asObj);
-    await applyGraphToEntity(session, targetTable, entity as AnyEntity, asObj, options);
+    const current =
+      findInCollectionByPk(existing, targetPk, pkValue) ??
+      (pkValue !== undefined && pkValue !== null ? session.getEntity(targetTable, pkValue) : undefined);
+
+    const entity = current ?? ensureEntity(session, targetTable, asObj, options);
+    assignColumns(targetTable, entity as AnyEntity, asObj, options);
+    await applyGraphToEntity(session, targetTable, entity as AnyEntity, asObj, options);
 
     if (!isEntityInCollection(collection.getItems() as unknown as AnyEntity[], targetPk, entity as unknown as AnyEntity)) {
       collection.attach(entity);
@@ -170,11 +206,11 @@ const handleHasOne = async (
     }
     return;
   }
-  const attached = ref.set(payload as AnyEntity);
-  if (attached) {
-    await applyGraphToEntity(session, relation.target, attached as AnyEntity, payload as AnyEntity, options);
-  }
-};
+  const attached = ref.set(payload as AnyEntity);
+  if (attached) {
+    await applyGraphToEntity(session, relation.target, attached as AnyEntity, payload as AnyEntity, options);
+  }
+};
 
 const handleBelongsTo = async (
   session: OrmSession,
@@ -198,11 +234,11 @@ const handleBelongsTo = async (
     }
     return;
   }
-  const attached = ref.set(payload as AnyEntity);
-  if (attached) {
-    await applyGraphToEntity(session, relation.target, attached as AnyEntity, payload as AnyEntity, options);
-  }
-};
+  const attached = ref.set(payload as AnyEntity);
+  if (attached) {
+    await applyGraphToEntity(session, relation.target, attached as AnyEntity, payload as AnyEntity, options);
+  }
+};
 
 const handleBelongsToMany = async (
   session: OrmSession,
@@ -229,14 +265,14 @@ const handleBelongsToMany = async (
       continue;
     }
 
-    const asObj = item as AnyEntity;
-    const pkValue = asObj[targetPk];
-    const entity = pkValue !== undefined && pkValue !== null
-      ? session.getEntity(targetTable, pkValue) ?? ensureEntity(session, targetTable, asObj)
-      : ensureEntity(session, targetTable, asObj);
-
-    assignColumns(targetTable, entity as AnyEntity, asObj);
-    await applyGraphToEntity(session, targetTable, entity as AnyEntity, asObj, options);
+    const asObj = item as AnyEntity;
+    const pkValue = asObj[targetPk];
+    const entity = pkValue !== undefined && pkValue !== null
+      ? session.getEntity(targetTable, pkValue) ?? ensureEntity(session, targetTable, asObj, options)
+      : ensureEntity(session, targetTable, asObj, options);
+
+    assignColumns(targetTable, entity as AnyEntity, asObj, options);
+    await applyGraphToEntity(session, targetTable, entity as AnyEntity, asObj, options);
 
     if (!isEntityInCollection(collection.getItems() as unknown as AnyEntity[], targetPk, entity as unknown as AnyEntity)) {
       collection.attach(entity);
@@ -278,36 +314,36 @@ const applyRelation = async (
   }
 };
 
-const applyGraphToEntity = async (
-  session: OrmSession,
-  table: TableDef,
-  entity: AnyEntity,
-  payload: AnyEntity,
-  options: SaveGraphOptions
-): Promise<void> => {
-  assignColumns(table, entity, payload);
-
-  for (const [relationName, relation] of Object.entries(table.relations)) {
-    if (!(relationName in payload)) continue;
-    await applyRelation(session, table, entity, relationName, relation as RelationDef, payload[relationName], options);
-  }
-};
-
-export const saveGraph = async <TTable extends TableDef>(
-  session: OrmSession,
-  entityClass: EntityConstructor,
-  payload: AnyEntity,
-  options: SaveGraphOptions = {}
-): Promise<EntityInstance<TTable>> => {
+const applyGraphToEntity = async (
+  session: OrmSession,
+  table: TableDef,
+  entity: AnyEntity,
+  payload: AnyEntity,
+  options: SaveGraphOptions
+): Promise<void> => {
+  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 as RelationDef, payload[relationName], options);
+  }
+};
+
+export const saveGraph = async <TTable extends TableDef>(
+  session: OrmSession,
+  entityClass: EntityConstructor,
+  payload: AnyEntity,
+  options: SaveGraphOptions = {}
+): Promise<EntityInstance<TTable>> => {
   const table = getTableDefFromEntity(entityClass);
   if (!table) {
     throw new Error('Entity metadata has not been bootstrapped');
   }
 
-  const root = ensureEntity<TTable>(session, table as TTable, payload);
-  await applyGraphToEntity(session, table, root as AnyEntity, payload, options);
-  return root;
-};
+  const root = ensureEntity<TTable>(session, table as TTable, payload, options);
+  await applyGraphToEntity(session, table, root as AnyEntity, payload, options);
+  return root;
+};
 
 /**
 
@@ -325,7 +361,7 @@ export const saveGraph = async <TTable extends TableDef>(
 
  */
 
-export const saveGraphInternal = async <TCtor extends EntityConstructor>(
+export const saveGraphInternal = async <TCtor extends EntityConstructor>(
 
   session: OrmSession,
 
@@ -337,7 +373,7 @@ export const saveGraphInternal = async <TCtor extends EntityConstructor>(
 
 ): Promise<InstanceType<TCtor>> => {
 
-  const table = getTableDefFromEntity(entityClass);
+  const table = getTableDefFromEntity(entityClass);
 
   if (!table) {
 
@@ -345,10 +381,10 @@ export const saveGraphInternal = async <TCtor extends EntityConstructor>(
 
   }
 
-  const root = ensureEntity(session, table, payload);
-
-  await applyGraphToEntity(session, table, root as AnyEntity, payload, options);
-
-  return root as unknown as InstanceType<TCtor>;
-
-};
+  const root = ensureEntity(session, table, payload, options);
+
+  await applyGraphToEntity(session, table, root as AnyEntity, payload, options);
+
+  return root as unknown as InstanceType<TCtor>;
+
+};