metal-orm 1.0.106 → 1.0.107

package/package.json

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

package/src/orm/entity.ts

@@ -1,151 +1,155 @@
-import { TableDef } from '../schema/table.js';
-import { EntityInstance } from '../schema/types.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';
-import { populateHydrationCache } from './entity-hydration.js';
-import { getRelationWrapper, RelationEntityFactory } from './entity-relations.js';
-
-export { relationLoaderCache } from './entity-relation-cache.js';
-
-const isRelationWrapperLoaded = (value: unknown): boolean => {
-  if (!value || typeof value !== 'object') return false;
-  return Boolean((value as { loaded?: boolean }).loaded);
-};
-
-type JsonSource<TTable extends TableDef> = EntityInstance<TTable> & Record<string, unknown>;
-
-/**
- * Creates an entity proxy with lazy loading capabilities.
- * @template TTable - The table type
- * @template TLazy - The lazy relation keys
- * @param ctx - The entity context
- * @param table - The table definition
- * @param row - The database row
- * @param lazyRelations - Optional lazy relations
- * @returns The entity instance
- */
-export const createEntityProxy = <
-  TTable extends TableDef,
-  TLazy extends RelationKey<TTable> = RelationKey<TTable>
->(
-  ctx: EntityContext,
-  table: TTable,
-  row: Record<string, unknown>,
-  lazyRelations: TLazy[] = [] as TLazy[],
-  lazyRelationOptions: Map<string, RelationIncludeOptions> = new Map()
-): EntityInstance<TTable> => {
-  const target: Record<string, unknown> = { ...row };
-  const meta: EntityMeta<TTable> = {
-    ctx,
-    table,
-    lazyRelations: [...lazyRelations],
-    lazyRelationOptions: new Map(lazyRelationOptions),
-    relationCache: new Map(),
-    relationHydration: new Map(),
-    relationWrappers: new Map()
-  };
-  const createRelationEntity: RelationEntityFactory = (relationTable, relationRow) =>
-    createEntityFromRow(meta.ctx, relationTable, relationRow);
-
-  const buildJson = (self: JsonSource<TTable>): Record<string, unknown> => {
-    const json: Record<string, unknown> = {};
-    for (const key of Object.keys(target)) {
-      json[key] = self[key];
-    }
-    for (const [relationName, wrapper] of meta.relationWrappers) {
-      if (Object.prototype.hasOwnProperty.call(json, relationName)) continue;
-      if (isRelationWrapperLoaded(wrapper)) {
-        json[relationName] = wrapper;
-      }
-    }
-    return json;
-  };
-
-  Object.defineProperty(target, ENTITY_META, {
-    value: meta,
-    enumerable: false,
-    writable: false
-  });
-
-  const handler: ProxyHandler<object> = {
-    get(targetObj, prop, receiver) {
-      if (prop === ENTITY_META) {
-        return meta;
-      }
-
-      if (prop === '$load') {
-        return async (relationName: RelationKey<TTable>) => {
-          const wrapper = getRelationWrapper(meta, relationName, receiver, createRelationEntity);
-          if (wrapper && typeof wrapper.load === 'function') {
-            return wrapper.load();
-          }
-          return undefined;
-        };
-      }
-
-      if (prop === 'toJSON') {
-        if (prop in targetObj) {
-          return Reflect.get(targetObj, prop, receiver);
-        }
-        return () => buildJson(receiver as JsonSource<TTable>);
-      }
-
-      if (typeof prop === 'string' && table.relations[prop]) {
-        return getRelationWrapper(meta, prop as RelationKey<TTable>, receiver, createRelationEntity);
-      }
-
-      return Reflect.get(targetObj, prop, receiver);
-    },
-
-    set(targetObj, prop, value, receiver) {
-      const result = Reflect.set(targetObj, prop, value, receiver);
-      if (typeof prop === 'string' && table.columns[prop]) {
-        ctx.markDirty(receiver);
-      }
-      return result;
-    }
-  };
-
-  const proxy = new Proxy(target, handler) as EntityInstance<TTable>;
-  populateHydrationCache(proxy, row, meta);
-  return proxy;
-};
-
-/**
- * Creates an entity instance from a database row.
- * @template TTable - The table type
- * @template TResult - The result type
- * @param ctx - The entity context
- * @param table - The table definition
- * @param row - The database row
- * @param lazyRelations - Optional lazy relations
- * @returns The entity instance
- */
-export const createEntityFromRow = <
-  TTable extends TableDef,
-  TResult extends EntityInstance<TTable> = EntityInstance<TTable>
->(
-  ctx: EntityContext,
-  table: TTable,
-  row: Record<string, unknown>,
-  lazyRelations: RelationKey<TTable>[] = [],
-  lazyRelationOptions: Map<string, RelationIncludeOptions> = new Map()
-): TResult => {
-  const pkName = findPrimaryKey(table);
-  const pkValue = row[pkName];
-  if (pkValue !== undefined && pkValue !== null) {
-    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);
-  } else {
-    ctx.trackNew(table, entity);
-  }
-
-  return entity as TResult;
-};
+import { TableDef } from '../schema/table.js';
+import { EntityInstance } from '../schema/types.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';
+import { populateHydrationCache } from './entity-hydration.js';
+import { getRelationWrapper, RelationEntityFactory } from './entity-relations.js';
+
+export { relationLoaderCache } from './entity-relation-cache.js';
+
+const isRelationWrapperLoaded = (value: unknown): boolean => {
+  if (!value || typeof value !== 'object') return false;
+  return Boolean((value as { loaded?: boolean }).loaded);
+};
+
+type JsonSource<TTable extends TableDef> = EntityInstance<TTable> & Record<string, unknown>;
+
+/**
+ * Creates an entity proxy with lazy loading capabilities.
+ * @template TTable - The table type
+ * @template TLazy - The lazy relation keys
+ * @param ctx - The entity context
+ * @param table - The table definition
+ * @param row - The database row
+ * @param lazyRelations - Optional lazy relations
+ * @returns The entity instance
+ */
+export const createEntityProxy = <
+  TTable extends TableDef,
+  TLazy extends RelationKey<TTable> = RelationKey<TTable>
+>(
+  ctx: EntityContext,
+  table: TTable,
+  row: Record<string, unknown>,
+  lazyRelations: TLazy[] = [] as TLazy[],
+  lazyRelationOptions: Map<string, RelationIncludeOptions> = new Map()
+): EntityInstance<TTable> => {
+  const target: Record<string, unknown> = { ...row };
+  const meta: EntityMeta<TTable> = {
+    ctx,
+    table,
+    lazyRelations: [...lazyRelations],
+    lazyRelationOptions: new Map(lazyRelationOptions),
+    relationCache: new Map(),
+    relationHydration: new Map(),
+    relationWrappers: new Map()
+  };
+  const createRelationEntity: RelationEntityFactory = (relationTable, relationRow) =>
+    createEntityFromRow(meta.ctx, relationTable, relationRow);
+
+  const buildJson = (self: JsonSource<TTable>): Record<string, unknown> => {
+    const json: Record<string, unknown> = {};
+    for (const key of Object.keys(target)) {
+      if (table.relations[key]) continue;
+      json[key] = self[key];
+    }
+    for (const relationName of Object.keys(table.relations)) {
+      const wrapper = self[relationName];
+      if (wrapper && isRelationWrapperLoaded(wrapper)) {
+        const wrapperWithToJSON = wrapper as { toJSON?: () => unknown };
+        json[relationName] = typeof wrapperWithToJSON.toJSON === 'function'
+          ? wrapperWithToJSON.toJSON()
+          : wrapper;
+      }
+    }
+    return json;
+  };
+
+  Object.defineProperty(target, ENTITY_META, {
+    value: meta,
+    enumerable: false,
+    writable: false
+  });
+
+  const handler: ProxyHandler<object> = {
+    get(targetObj, prop, receiver) {
+      if (prop === ENTITY_META) {
+        return meta;
+      }
+
+      if (prop === '$load') {
+        return async (relationName: RelationKey<TTable>) => {
+          const wrapper = getRelationWrapper(meta, relationName, receiver, createRelationEntity);
+          if (wrapper && typeof wrapper.load === 'function') {
+            return wrapper.load();
+          }
+          return undefined;
+        };
+      }
+
+      if (prop === 'toJSON') {
+        if (prop in targetObj) {
+          return Reflect.get(targetObj, prop, receiver);
+        }
+        return () => buildJson(receiver as JsonSource<TTable>);
+      }
+
+      if (typeof prop === 'string' && table.relations[prop]) {
+        return getRelationWrapper(meta, prop as RelationKey<TTable>, receiver, createRelationEntity);
+      }
+
+      return Reflect.get(targetObj, prop, receiver);
+    },
+
+    set(targetObj, prop, value, receiver) {
+      const result = Reflect.set(targetObj, prop, value, receiver);
+      if (typeof prop === 'string' && table.columns[prop]) {
+        ctx.markDirty(receiver);
+      }
+      return result;
+    }
+  };
+
+  const proxy = new Proxy(target, handler) as EntityInstance<TTable>;
+  populateHydrationCache(proxy, row, meta);
+  return proxy;
+};
+
+/**
+ * Creates an entity instance from a database row.
+ * @template TTable - The table type
+ * @template TResult - The result type
+ * @param ctx - The entity context
+ * @param table - The table definition
+ * @param row - The database row
+ * @param lazyRelations - Optional lazy relations
+ * @returns The entity instance
+ */
+export const createEntityFromRow = <
+  TTable extends TableDef,
+  TResult extends EntityInstance<TTable> = EntityInstance<TTable>
+>(
+  ctx: EntityContext,
+  table: TTable,
+  row: Record<string, unknown>,
+  lazyRelations: RelationKey<TTable>[] = [],
+  lazyRelationOptions: Map<string, RelationIncludeOptions> = new Map()
+): TResult => {
+  const pkName = findPrimaryKey(table);
+  const pkValue = row[pkName];
+  if (pkValue !== undefined && pkValue !== null) {
+    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);
+  } else {
+    ctx.trackNew(table, entity);
+  }
+
+  return entity as TResult;
+};

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

@@ -1,126 +1,139 @@
-import { BelongsToReferenceApi } from '../../schema/types.js';
-import { EntityContext } from '../entity-context.js';
-import { RelationKey } from '../runtime-types.js';
-import { BelongsToRelation } from '../../schema/relation.js';
-import { TableDef } from '../../schema/table.js';
-import { EntityMeta, getHydrationRecord, hasEntityMeta } from '../entity-meta.js';
-
-type Rows = Record<string, unknown>;
-
-const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
-
-const hideInternal = (obj: object, keys: string[]): void => {
-  for (const key of keys) {
-    Object.defineProperty(obj, key, {
-      value: obj[key],
-      writable: false,
-      configurable: false,
-      enumerable: false
-    });
-  }
-};
-
-/**
- * Default implementation of a belongs-to reference.
- * Manages a reference to a parent entity from a child entity through a foreign key.
- *
- * @template TParent The type of the parent entity.
- */
-export class DefaultBelongsToReference<TParent extends object> implements BelongsToReferenceApi<TParent> {
-  private loaded = false;
-  private current: TParent | null = null;
-
-  /**
-   * @param ctx The entity context for tracking changes.
-   * @param meta Metadata for the child entity.
-   * @param root The child entity instance (carrying the foreign key).
-   * @param relationName The name of the relation.
-   * @param relation Relation definition.
-   * @param rootTable Table definition of the child entity.
-   * @param loader Function to load the parent entity.
-   * @param createEntity Function to create entity instances from rows.
-   * @param targetKey The primary key of the target (parent) table.
-   */
-  constructor(
-    private readonly ctx: EntityContext,
-    private readonly meta: EntityMeta<TableDef>,
-    private readonly root: unknown,
-    private readonly relationName: string,
-    private readonly relation: BelongsToRelation,
-    private readonly rootTable: TableDef,
-    private readonly loader: () => Promise<Map<string, Rows>>,
-    private readonly createEntity: (row: Record<string, unknown>) => TParent,
-    private readonly targetKey: string
-  ) {
-    hideInternal(this, ['ctx', 'meta', 'root', 'relationName', 'relation', 'rootTable', 'loader', 'createEntity', 'targetKey']);
-    this.populateFromHydrationCache();
-  }
-
-  async load(): Promise<TParent | null> {
-    if (this.loaded) return this.current;
-    const map = await this.loader();
-    const fkValue = (this.root as Record<string, unknown>)[this.relation.foreignKey];
-    if (fkValue === null || fkValue === undefined) {
-      this.current = null;
-    } else {
-      const row = map.get(toKey(fkValue));
-      this.current = row ? this.createEntity(row) : null;
-    }
-    this.loaded = true;
-    return this.current;
-  }
-
-  get(): TParent | null {
-    return this.current;
-  }
-
-  set(data: Partial<TParent> | TParent | null): TParent | null {
-    if (data === null) {
-      const previous = this.current;
-      (this.root as Record<string, unknown>)[this.relation.foreignKey] = null;
-      this.current = null;
-      this.ctx.registerRelationChange(
-        this.root,
-        this.relationKey,
-        this.rootTable,
-        this.relationName,
-        this.relation,
-        { kind: 'remove', entity: previous }
-      );
-      return null;
-    }
-
-    const entity = hasEntityMeta(data) ? (data as TParent) : this.createEntity(data as Record<string, unknown>);
-    const pkValue = (entity as Record<string, unknown>)[this.targetKey];
-    if (pkValue !== undefined) {
-      (this.root as Record<string, unknown>)[this.relation.foreignKey] = pkValue;
-    }
-    this.current = entity;
-    this.ctx.registerRelationChange(
-      this.root,
-      this.relationKey,
-      this.rootTable,
-      this.relationName,
-      this.relation,
-      { kind: 'attach', entity }
-    );
-    return entity;
-  }
-
-  private get relationKey(): RelationKey {
-    return `${this.rootTable.name}.${this.relationName}`;
-  }
-
-  private populateFromHydrationCache(): void {
-    const fkValue = (this.root as Record<string, unknown>)[this.relation.foreignKey];
-    if (fkValue === undefined || fkValue === null) return;
-    const row = getHydrationRecord(this.meta, this.relationName, fkValue);
-    if (!row) return;
-    this.current = this.createEntity(row);
-    this.loaded = true;
-  }
-
-  toJSON(): TParent | null {
-    return this.current;
-  }
-}
+import { BelongsToReferenceApi } from '../../schema/types.js';
+import { EntityContext } from '../entity-context.js';
+import { RelationKey } from '../runtime-types.js';
+import { BelongsToRelation } from '../../schema/relation.js';
+import { TableDef } from '../../schema/table.js';
+import { EntityMeta, getHydrationRecord, hasEntityMeta } from '../entity-meta.js';
+
+type Rows = Record<string, unknown>;
+
+const toKey = (value: unknown): string => (value === null || value === undefined ? '' : String(value));
+
+const hideInternal = (obj: object, keys: string[]): void => {
+  for (const key of keys) {
+    Object.defineProperty(obj, key, {
+      value: obj[key],
+      writable: false,
+      configurable: false,
+      enumerable: false
+    });
+  }
+};
+
+const hideWritable = (obj: object, keys: string[]): void => {
+  for (const key of keys) {
+    const value = obj[key as keyof typeof obj];
+    Object.defineProperty(obj, key, {
+      value,
+      writable: true,
+      configurable: true,
+      enumerable: false
+    });
+  }
+};
+
+/**
+ * Default implementation of a belongs-to reference.
+ * Manages a reference to a parent entity from a child entity through a foreign key.
+ *
+ * @template TParent The type of the parent entity.
+ */
+export class DefaultBelongsToReference<TParent extends object> implements BelongsToReferenceApi<TParent> {
+  private loaded = false;
+  private current: TParent | null = null;
+
+  /**
+   * @param ctx The entity context for tracking changes.
+   * @param meta Metadata for the child entity.
+   * @param root The child entity instance (carrying the foreign key).
+   * @param relationName The name of the relation.
+   * @param relation Relation definition.
+   * @param rootTable Table definition of the child entity.
+   * @param loader Function to load the parent entity.
+   * @param createEntity Function to create entity instances from rows.
+   * @param targetKey The primary key of the target (parent) table.
+   */
+  constructor(
+    private readonly ctx: EntityContext,
+    private readonly meta: EntityMeta<TableDef>,
+    private readonly root: unknown,
+    private readonly relationName: string,
+    private readonly relation: BelongsToRelation,
+    private readonly rootTable: TableDef,
+    private readonly loader: () => Promise<Map<string, Rows>>,
+    private readonly createEntity: (row: Record<string, unknown>) => TParent,
+    private readonly targetKey: string
+  ) {
+    hideInternal(this, ['ctx', 'meta', 'root', 'relationName', 'relation', 'rootTable', 'loader', 'createEntity', 'targetKey']);
+    hideWritable(this, ['loaded', 'current']);
+    this.populateFromHydrationCache();
+  }
+
+  async load(): Promise<TParent | null> {
+    if (this.loaded) return this.current;
+    const map = await this.loader();
+    const fkValue = (this.root as Record<string, unknown>)[this.relation.foreignKey];
+    if (fkValue === null || fkValue === undefined) {
+      this.current = null;
+    } else {
+      const row = map.get(toKey(fkValue));
+      this.current = row ? this.createEntity(row) : null;
+    }
+    this.loaded = true;
+    return this.current;
+  }
+
+  get(): TParent | null {
+    return this.current;
+  }
+
+  set(data: Partial<TParent> | TParent | null): TParent | null {
+    if (data === null) {
+      const previous = this.current;
+      (this.root as Record<string, unknown>)[this.relation.foreignKey] = null;
+      this.current = null;
+      this.ctx.registerRelationChange(
+        this.root,
+        this.relationKey,
+        this.rootTable,
+        this.relationName,
+        this.relation,
+        { kind: 'remove', entity: previous }
+      );
+      return null;
+    }
+
+    const entity = hasEntityMeta(data) ? (data as TParent) : this.createEntity(data as Record<string, unknown>);
+    const pkValue = (entity as Record<string, unknown>)[this.targetKey];
+    if (pkValue !== undefined) {
+      (this.root as Record<string, unknown>)[this.relation.foreignKey] = pkValue;
+    }
+    this.current = entity;
+    this.ctx.registerRelationChange(
+      this.root,
+      this.relationKey,
+      this.rootTable,
+      this.relationName,
+      this.relation,
+      { kind: 'attach', entity }
+    );
+    return entity;
+  }
+
+  private get relationKey(): RelationKey {
+    return `${this.rootTable.name}.${this.relationName}`;
+  }
+
+  private populateFromHydrationCache(): void {
+    const fkValue = (this.root as Record<string, unknown>)[this.relation.foreignKey];
+    if (fkValue === undefined || fkValue === null) return;
+    const row = getHydrationRecord(this.meta, this.relationName, fkValue);
+    if (!row) return;
+    this.current = this.createEntity(row);
+    this.loaded = true;
+  }
+
+  toJSON(): TParent | null {
+    return this.current;
+  }
+}