metal-orm 1.0.65 → 1.0.67

package/src/orm/entity-relation-cache.ts

@@ -1,39 +1,39 @@
-import { TableDef } from '../schema/table.js';
-import { EntityMeta, getEntityMeta } from './entity-meta.js';
-
-/**
- * Caches relation loader results across entities of the same type.
- * @template T - The cache type
- * @param meta - The entity metadata
- * @param relationName - The relation name
- * @param factory - The factory function to create the cache
- * @returns Promise with the cached relation data
- */
-export const relationLoaderCache = <TTable extends TableDef, T extends Map<string, unknown>>(
-  meta: EntityMeta<TTable>,
-  relationName: string,
-  factory: () => Promise<T>
-): Promise<T> => {
-  if (meta.relationCache.has(relationName)) {
-    return meta.relationCache.get(relationName)! as Promise<T>;
-  }
-
-  const promise = factory().then(value => {
-    for (const tracked of meta.ctx.getEntitiesForTable(meta.table)) {
-      const otherMeta = getEntityMeta(tracked.entity);
-      if (!otherMeta) continue;
-      otherMeta.relationHydration.set(relationName, value);
-    }
-    return value;
-  });
-
-  meta.relationCache.set(relationName, promise);
-
-  for (const tracked of meta.ctx.getEntitiesForTable(meta.table)) {
-    const otherMeta = getEntityMeta(tracked.entity);
-    if (!otherMeta) continue;
-    otherMeta.relationCache.set(relationName, promise);
-  }
-
-  return promise;
-};
+import { TableDef } from '../schema/table.js';
+import { EntityMeta, getEntityMeta } from './entity-meta.js';
+
+/**
+ * Caches relation loader results across entities of the same type.
+ * @template T - The cache type
+ * @param meta - The entity metadata
+ * @param relationName - The relation name
+ * @param factory - The factory function to create the cache
+ * @returns Promise with the cached relation data
+ */
+export const relationLoaderCache = <TTable extends TableDef, T extends Map<string, unknown>>(
+  meta: EntityMeta<TTable>,
+  relationName: string,
+  factory: () => Promise<T>
+): Promise<T> => {
+  if (meta.relationCache.has(relationName)) {
+    return meta.relationCache.get(relationName)! as Promise<T>;
+  }
+
+  const promise = factory().then(value => {
+    for (const tracked of meta.ctx.getEntitiesForTable(meta.table)) {
+      const otherMeta = getEntityMeta(tracked.entity);
+      if (!otherMeta) continue;
+      otherMeta.relationHydration.set(relationName, value);
+    }
+    return value;
+  });
+
+  meta.relationCache.set(relationName, promise);
+
+  for (const tracked of meta.ctx.getEntitiesForTable(meta.table)) {
+    const otherMeta = getEntityMeta(tracked.entity);
+    if (!otherMeta) continue;
+    otherMeta.relationCache.set(relationName, promise);
+  }
+
+  return promise;
+};

package/src/orm/entity.ts

@@ -1,6 +1,6 @@
 import { TableDef } from '../schema/table.js';
 import { EntityInstance } from '../schema/types.js';
-import type { EntityContext, PrimaryKey } from './entity-context.js';
+import type { EntityContext, PrimaryKey } from './entity-context.js';
 import { ENTITY_META, EntityMeta, RelationKey } from './entity-meta.js';
 import { findPrimaryKey } from '../query-builder/hydration-planner.js';
 import { RelationIncludeOptions } from '../query-builder/relation-types.js';
@@ -109,13 +109,13 @@ export const createEntityFromRow = <
   const pkName = findPrimaryKey(table);
   const pkValue = row[pkName];
   if (pkValue !== undefined && pkValue !== null) {
-    const tracked = ctx.getEntity(table, pkValue as PrimaryKey);
+    const tracked = ctx.getEntity(table, pkValue as PrimaryKey);
     if (tracked) return tracked as TResult;
   }
 
   const entity = createEntityProxy(ctx, table, row, lazyRelations, lazyRelationOptions);
   if (pkValue !== undefined && pkValue !== null) {
-    ctx.trackManaged(table, pkValue as PrimaryKey, entity);
+    ctx.trackManaged(table, pkValue as PrimaryKey, entity);
   } else {
     ctx.trackNew(table, entity);
   }

package/src/orm/identity-map.ts

@@ -1,5 +1,6 @@
 import type { TableDef } from '../schema/table.js';
 import type { TrackedEntity } from './runtime-types.js';
+import type { PrimaryKey } from './entity-context.js';
 
 /**
  * Simple identity map for tracking entities within a session.
@@ -18,7 +19,7 @@ export class IdentityMap {
    * @param pk The primary key value.
    * @returns The entity instance if found, undefined otherwise.
    */
-  getEntity(table: TableDef, pk: string | number): object | undefined {
+  getEntity(table: TableDef, pk: PrimaryKey): object | undefined {
     const bucket = this.buckets.get(table.name);
     return bucket?.get(this.toIdentityKey(pk))?.entity;
   }
@@ -54,7 +55,7 @@ export class IdentityMap {
     this.buckets.clear();
   }
 
-  private toIdentityKey(pk: string | number): string {
+  private toIdentityKey(pk: PrimaryKey): string {
     return String(pk);
   }
 }

package/src/orm/relations/belongs-to.ts

@@ -1,4 +1,4 @@
-import { BelongsToReferenceApi } from '../../schema/types.js';
+import { BelongsToReferenceApi } from '../../schema/types.js';
 import { EntityContext } from '../entity-context.js';
 import { RelationKey } from '../runtime-types.js';
 import { BelongsToRelation } from '../../schema/relation.js';
@@ -26,7 +26,7 @@ const hideInternal = (obj: object, keys: string[]): void => {
  *
  * @template TParent The type of the parent entity.
  */
-export class DefaultBelongsToReference<TParent extends object> implements BelongsToReferenceApi<TParent> {
+export class DefaultBelongsToReference<TParent extends object> implements BelongsToReferenceApi<TParent> {
   private loaded = false;
   private current: TParent | null = null;
 

package/src/orm/relations/has-many.ts

@@ -69,29 +69,29 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
     this.items = rows.map(row => this.createEntity(row));
     this.loaded = true;
     return this.items;
-  }
-
-  /**
-   * Gets the current items in the collection.
-   * @returns Array of child entities
-   */
-  getItems(): TChild[] {
-    return this.items;
-  }
- 
-  /**
-   * Array-compatible length for testing frameworks.
-   */
-  get length(): number {
-    return this.items.length;
-  }
-
-  /**
-   * Enables iteration over the collection like an array.
-   */
-  [Symbol.iterator](): Iterator<TChild> {
-    return this.items[Symbol.iterator]();
-  }
+  }
+
+  /**
+   * Gets the current items in the collection.
+   * @returns Array of child entities
+   */
+  getItems(): TChild[] {
+    return this.items;
+  }
+ 
+  /**
+   * Array-compatible length for testing frameworks.
+   */
+  get length(): number {
+    return this.items.length;
+  }
+
+  /**
+   * Enables iteration over the collection like an array.
+   */
+  [Symbol.iterator](): Iterator<TChild> {
+    return this.items[Symbol.iterator]();
+  }
 
   /**
    * Adds a new child entity to the collection.
@@ -125,7 +125,7 @@ export class DefaultHasManyCollection<TChild> implements HasManyCollection<TChil
   attach(entity: TChild): void {
     const keyValue = this.root[this.localKey];
     (entity as Record<string, unknown>)[this.relation.foreignKey] = keyValue;
-    this.ctx.markDirty(entity as object);
+    this.ctx.markDirty(entity as object);
     this.items.push(entity);
     this.ctx.registerRelationChange(
       this.root,

package/src/orm/relations/has-one.ts

@@ -1,4 +1,4 @@
-import { HasOneReferenceApi } from '../../schema/types.js';
+import { HasOneReferenceApi } from '../../schema/types.js';
 import { EntityContext } from '../entity-context.js';
 import { RelationKey } from '../runtime-types.js';
 import { HasOneRelation } from '../../schema/relation.js';
@@ -26,7 +26,7 @@ const hideInternal = (obj: object, keys: string[]): void => {
  *
  * @template TChild The type of the child entity.
  */
-export class DefaultHasOneReference<TChild extends object> implements HasOneReferenceApi<TChild> {
+export class DefaultHasOneReference<TChild extends object> implements HasOneReferenceApi<TChild> {
   private loaded = false;
   private current: TChild | null = null;
 

package/src/orm/relations/many-to-many.ts

@@ -28,8 +28,8 @@ const hideInternal = (obj: object, keys: string[]): void => {
  *
  * @template TTarget The type of the target entities in the collection.
  */
-export class DefaultManyToManyCollection<TTarget, TPivot extends object | undefined = undefined>
-  implements ManyToManyCollection<TTarget, TPivot> {
+export class DefaultManyToManyCollection<TTarget, TPivot extends object | undefined = undefined>
+  implements ManyToManyCollection<TTarget, TPivot> {
   private loaded = false;
   private items: TTarget[] = [];
 
@@ -79,33 +79,33 @@ export class DefaultManyToManyCollection<TTarget, TPivot extends object | undefi
     return this.items;
   }
 
-  /**
-   * Returns the currently loaded items.
-   * @returns Array of target entities.
-   */
-  getItems(): TTarget[] {
-    return this.items;
-  }
-
-  /**
-   * Array-compatible length for testing frameworks.
-   */
-  get length(): number {
-    return this.items.length;
-  }
-
-  /**
-   * Enables iteration over the collection like an array.
-   */
-  [Symbol.iterator](): Iterator<TTarget> {
-    return this.items[Symbol.iterator]();
-  }
-
-  /**
-   * Attaches an entity to the collection.
-   * Registers an 'attach' change in the entity context.
-   * @param target Entity instance or its primary key value.
-   */
+  /**
+   * Returns the currently loaded items.
+   * @returns Array of target entities.
+   */
+  getItems(): TTarget[] {
+    return this.items;
+  }
+
+  /**
+   * Array-compatible length for testing frameworks.
+   */
+  get length(): number {
+    return this.items.length;
+  }
+
+  /**
+   * Enables iteration over the collection like an array.
+   */
+  [Symbol.iterator](): Iterator<TTarget> {
+    return this.items[Symbol.iterator]();
+  }
+
+  /**
+   * Attaches an entity to the collection.
+   * Registers an 'attach' change in the entity context.
+   * @param target Entity instance or its primary key value.
+   */
   attach(target: TTarget | number | string): void {
     const entity = this.ensureEntity(target);
     const id = this.extractId(entity);

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

@@ -1,55 +1,56 @@
-import type {
-  BelongsToReference,
-  HasManyCollection,
-  HasOneReference,
-  ManyToManyCollection
-} from '../schema/types.js';
-
-type AnyId = number | string;
-type AnyFn = (...args: unknown[]) => unknown;
-
-type RelationWrapper =
-  | HasManyCollection<unknown>
-  | HasOneReference
-  | BelongsToReference
-  | 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;
-
+import type {
+  BelongsToReference,
+  HasManyCollection,
+  HasOneReference,
+  ManyToManyCollection
+} from '../schema/types.js';
+
+type AnyId = number | string;
+type AnyFn = (...args: unknown[]) => unknown;
+
+type RelationWrapper =
+  | HasManyCollection<unknown>
+  | HasOneReference
+  | BelongsToReference
+  | 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 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'`.
  */
-export type SaveGraphInputScalar<T> = 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.
- */
-export type SaveGraphInputPayload<TEntity> = ColumnInput<TEntity> & RelationInput<TEntity>;
+export type SaveGraphInputScalar<T> = T extends Date ? T | string | number : 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.
+ */
+export type SaveGraphInputPayload<TEntity> = ColumnInput<TEntity> & RelationInput<TEntity>;

package/src/orm/save-graph.ts

@@ -20,6 +20,7 @@ import { createEntityFromRow } from './entity.js';
 import type { EntityConstructor } from './entity-metadata.js';
 import { getTableDefFromEntity } from '../decorators/bootstrap.js';
 import type { OrmSession } from './orm-session.js';
+import type { PrimaryKey } from './entity-context.js';
 
 /**
  * Options for controlling the behavior of save graph operations.
@@ -27,18 +28,16 @@ import type { OrmSession } from './orm-session.js';
 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';
-}
+  /**
+   * Coerce JSON-friendly input values into DB-friendly primitives.
+   * Currently:
+   * - `json`: Date -> ISO string (for DATE/DATETIME/TIMESTAMP/TIMESTAMPTZ columns)
+   * - `json-in`: string/number -> Date (for DATE/DATETIME/TIMESTAMP/TIMESTAMPTZ columns)
+   */
+  coerce?: 'json' | 'json-in';
+}
 
 /** Represents an entity object with arbitrary properties. */
-
-/** Represents an entity object with arbitrary properties. */
-
 type AnyEntity = Record<string, unknown>;
 
 /**
@@ -53,33 +52,49 @@ type AnyEntity = Record<string, unknown>;
 
 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 coerceColumnValue = (
+  table: TableDef,
+  columnName: string,
+  value: unknown,
+  options: SaveGraphOptions
+): unknown => {
+  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 isDateLikeColumn =
+    normalized === 'date' ||
+    normalized === 'datetime' ||
+    normalized === 'timestamp' ||
+    normalized === 'timestamptz';
+
+  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;
+  }
+
+  // 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> = {};
@@ -102,7 +117,7 @@ const ensureEntity = <TTable extends TableDef>(
   const pkValue = payload[pk];
 
   if (pkValue !== undefined && pkValue !== null) {
-    const tracked = session.getEntity(table, pkValue as string | number);
+    const tracked = session.getEntity(table, pkValue as PrimaryKey);
     if (tracked) {
       return tracked as EntityInstance<TTable>;
     }
@@ -159,7 +174,7 @@ const handleHasMany = async (
 
     const current =
       findInCollectionByPk(existing, targetPk, pkValue) ??
-      (pkValue !== undefined && pkValue !== null ? session.getEntity(targetTable, pkValue as string | number) : undefined);
+      (pkValue !== undefined && pkValue !== null ? session.getEntity(targetTable, pkValue as PrimaryKey) : undefined);
 
     const entity = current ?? ensureEntity(session, targetTable, asObj, options);
     assignColumns(targetTable, entity as AnyEntity, asObj, options);
@@ -202,7 +217,7 @@ const handleHasOne = async (
   if (typeof payload === 'number' || typeof payload === 'string') {
     const entity = ref.set({ [pk]: payload });
     if (entity) {
-      await applyGraphToEntity(session, relation.target, entity as AnyEntity, { [pk]: payload }, options);
+      await applyGraphToEntity(session, relation.target, entity as AnyEntity, { [pk]: payload as PrimaryKey }, options);
     }
     return;
   }
@@ -230,7 +245,7 @@ const handleBelongsTo = async (
   if (typeof payload === 'number' || typeof payload === 'string') {
     const entity = ref.set({ [pk]: payload });
     if (entity) {
-      await applyGraphToEntity(session, relation.target, entity as AnyEntity, { [pk]: payload }, options);
+      await applyGraphToEntity(session, relation.target, entity as AnyEntity, { [pk]: payload as PrimaryKey }, options);
     }
     return;
   }
@@ -268,7 +283,7 @@ const handleBelongsToMany = async (
     const asObj = item as AnyEntity;
     const pkValue = asObj[targetPk];
     const entity = pkValue !== undefined && pkValue !== null
-      ? session.getEntity(targetTable, pkValue as string | number) ?? ensureEntity(session, targetTable, asObj, options)
+      ? session.getEntity(targetTable, pkValue as PrimaryKey) ?? ensureEntity(session, targetTable, asObj, options)
       : ensureEntity(session, targetTable, asObj, options);
 
     assignColumns(targetTable, entity as AnyEntity, asObj, options);