metal-orm 1.1.8 → 1.1.10

package/src/schema/types.ts

@@ -1,105 +1,120 @@
-import type { ColumnDef } from './column-types.js';
-export type { ColumnDef };
-import { TableDef } from './table.js';
-import {
-  RelationDef,
-  HasManyRelation,
-  HasOneRelation,
-  BelongsToRelation,
-  BelongsToManyRelation
-} from './relation.js';
-
-/**
- * Resolves a relation definition to its target table type.
- */
-export type RelationTargetTable<TRel extends RelationDef> =
-  TRel extends HasManyRelation<infer TTarget> ? TTarget :
-  TRel extends HasOneRelation<infer TTarget> ? TTarget :
-  TRel extends BelongsToRelation<infer TTarget> ? TTarget :
-  TRel extends BelongsToManyRelation<infer TTarget, TableDef> ? TTarget :
-  never;
-
-export type JsonValue = string | number | boolean | null | JsonArray | JsonObject;
-export type JsonArray = Array<JsonValue>;
-export interface JsonObject { [key: string]: JsonValue }
-
-type NormalizedColumnType<T extends ColumnDef> = Lowercase<T['type'] & string>;
-
-/**
- * Maps a ColumnDef to its TypeScript type representation
- */
-export type ColumnToTs<T extends ColumnDef> =
-  [unknown] extends [T['tsType']]
-  ? NormalizedColumnType<T> extends 'int' | 'integer' ? number :
-  NormalizedColumnType<T> extends 'bigint' ? number | bigint :
-  NormalizedColumnType<T> extends 'decimal' | 'float' | 'double' ? number :
-  NormalizedColumnType<T> extends 'boolean' ? boolean :
-  NormalizedColumnType<T> extends 'json' ? JsonValue :
-  NormalizedColumnType<T> extends 'blob' | 'binary' | 'varbinary' | 'bytea' ? Buffer :
-  NormalizedColumnType<T> extends 'date' | 'datetime' | 'timestamp' | 'timestamptz' ? string :
-  string
-  : Exclude<T['tsType'], undefined>;
-
-/**
- * Infers a row shape from a table definition
- */
-export type InferRow<TTable extends TableDef> = {
-  [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
-};
-
-type RelationResult<T extends RelationDef> =
-  T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] :
-  T extends HasOneRelation<infer TTarget> ? InferRow<TTarget> | null :
-  T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null :
-  T extends BelongsToManyRelation<infer TTarget, infer TPivot> ? (InferRow<TTarget> & { _pivot?: InferRow<TPivot> })[] :
-  never;
-
-/**
- * Maps relation names to the expected row results
- */
-export type RelationMap<TTable extends TableDef> = {
-  [K in keyof TTable['relations']]: RelationResult<TTable['relations'][K]>;
-};
-
-type RelationWrapper<TRel extends RelationDef> =
-  TRel extends HasManyRelation<infer TTarget>
-  ? HasManyCollection<EntityInstance<TTarget>> & ReadonlyArray<EntityInstance<TTarget>>
-  : TRel extends HasOneRelation<infer TTarget>
-  ? HasOneReference<EntityInstance<TTarget>>
-  : TRel extends BelongsToManyRelation<infer TTarget, infer TPivot>
-  ? ManyToManyCollection<EntityInstance<TTarget> & { _pivot?: InferRow<TPivot> }>
-  & ReadonlyArray<EntityInstance<TTarget> & { _pivot?: InferRow<TPivot> }>
-  : TRel extends BelongsToRelation<infer TTarget>
-  ? BelongsToReference<EntityInstance<TTarget>>
-  : never;
-
-export interface HasManyCollection<TChild> {
-  length: number;
-  [Symbol.iterator](): Iterator<TChild>;
-  load(): Promise<TChild[]>;
-  getItems(): TChild[];
-  add(data: Partial<TChild>): TChild;
-  attach(entity: TChild): void;
-  remove(entity: TChild): void;
-  clear(): void;
-}
-
-export interface BelongsToReferenceApi<TParent extends object = object> {
-  load(): Promise<TParent | null>;
-  get(): TParent | null;
-  set(data: Partial<TParent> | TParent | null): TParent | null;
-}
-
-export type BelongsToReference<TParent extends object = object> = BelongsToReferenceApi<TParent> & Partial<TParent>;
-
-export interface HasOneReferenceApi<TChild extends object = object> {
-  load(): Promise<TChild | null>;
-  get(): TChild | null;
-  set(data: Partial<TChild> | TChild | null): TChild | null;
-}
-
-export type HasOneReference<TChild extends object = object> = HasOneReferenceApi<TChild> & Partial<TChild>;
-
+import type { ColumnDef } from './column-types.js';
+export type { ColumnDef };
+import { TableDef } from './table.js';
+import {
+  RelationDef,
+  HasManyRelation,
+  HasOneRelation,
+  BelongsToRelation,
+  BelongsToManyRelation,
+  MorphToRelation,
+  MorphOneRelation,
+  MorphManyRelation
+} from './relation.js';
+
+/**
+ * Resolves a relation definition to its target table type.
+ */
+export type RelationTargetTable<TRel extends RelationDef> =
+  TRel extends HasManyRelation<infer TTarget> ? TTarget :
+  TRel extends HasOneRelation<infer TTarget> ? TTarget :
+  TRel extends BelongsToRelation<infer TTarget> ? TTarget :
+  TRel extends BelongsToManyRelation<infer TTarget, TableDef> ? TTarget :
+  TRel extends MorphOneRelation<infer TTarget> ? TTarget :
+  TRel extends MorphManyRelation<infer TTarget> ? TTarget :
+  TRel extends MorphToRelation ? never :
+  never;
+
+export type JsonValue = string | number | boolean | null | JsonArray | JsonObject;
+export type JsonArray = Array<JsonValue>;
+export interface JsonObject { [key: string]: JsonValue }
+
+type NormalizedColumnType<T extends ColumnDef> = Lowercase<T['type'] & string>;
+
+/**
+ * Maps a ColumnDef to its TypeScript type representation
+ */
+export type ColumnToTs<T extends ColumnDef> =
+  [unknown] extends [T['tsType']]
+  ? NormalizedColumnType<T> extends 'int' | 'integer' ? number :
+  NormalizedColumnType<T> extends 'bigint' ? number | bigint :
+  NormalizedColumnType<T> extends 'decimal' | 'float' | 'double' ? number :
+  NormalizedColumnType<T> extends 'boolean' ? boolean :
+  NormalizedColumnType<T> extends 'json' ? JsonValue :
+  NormalizedColumnType<T> extends 'blob' | 'binary' | 'varbinary' | 'bytea' ? Buffer :
+  NormalizedColumnType<T> extends 'date' | 'datetime' | 'timestamp' | 'timestamptz' ? string :
+  string
+  : Exclude<T['tsType'], undefined>;
+
+/**
+ * Infers a row shape from a table definition
+ */
+export type InferRow<TTable extends TableDef> = {
+  [K in keyof TTable['columns']]: ColumnToTs<TTable['columns'][K]>;
+};
+
+type RelationResult<T extends RelationDef> =
+  T extends HasManyRelation<infer TTarget> ? InferRow<TTarget>[] :
+  T extends HasOneRelation<infer TTarget> ? InferRow<TTarget> | null :
+  T extends BelongsToRelation<infer TTarget> ? InferRow<TTarget> | null :
+  T extends BelongsToManyRelation<infer TTarget, infer TPivot> ? (InferRow<TTarget> & { _pivot?: InferRow<TPivot> })[] :
+  T extends MorphOneRelation<infer TTarget> ? InferRow<TTarget> | null :
+  T extends MorphManyRelation<infer TTarget> ? InferRow<TTarget>[] :
+  T extends MorphToRelation ? Record<string, unknown> | null :
+  never;
+
+/**
+ * Maps relation names to the expected row results
+ */
+export type RelationMap<TTable extends TableDef> = {
+  [K in keyof TTable['relations']]: RelationResult<TTable['relations'][K]>;
+};
+
+type RelationWrapper<TRel extends RelationDef> =
+  TRel extends HasManyRelation<infer TTarget>
+  ? HasManyCollection<EntityInstance<TTarget>> & ReadonlyArray<EntityInstance<TTarget>>
+  : TRel extends HasOneRelation<infer TTarget>
+  ? HasOneReference<EntityInstance<TTarget>>
+  : TRel extends BelongsToManyRelation<infer TTarget, infer TPivot>
+  ? ManyToManyCollection<EntityInstance<TTarget> & { _pivot?: InferRow<TPivot> }>
+  & ReadonlyArray<EntityInstance<TTarget> & { _pivot?: InferRow<TPivot> }>
+  : TRel extends BelongsToRelation<infer TTarget>
+  ? BelongsToReference<EntityInstance<TTarget>>
+  : TRel extends MorphOneRelation<infer TTarget>
+  ? HasOneReference<EntityInstance<TTarget>>
+  : TRel extends MorphManyRelation<infer TTarget>
+  ? HasManyCollection<EntityInstance<TTarget>> & ReadonlyArray<EntityInstance<TTarget>>
+  : TRel extends MorphToRelation
+  ? BelongsToReference<EntityInstance<TableDef>>
+  : never;
+
+export interface HasManyCollection<TChild> {
+  length: number;
+  [Symbol.iterator](): Iterator<TChild>;
+  load(): Promise<TChild[]>;
+  getItems(): TChild[];
+  add(data: Partial<TChild>): TChild;
+  attach(entity: TChild): void;
+  remove(entity: TChild): void;
+  clear(): void;
+}
+
+export interface BelongsToReferenceApi<TParent extends object = object> {
+  load(): Promise<TParent | null>;
+  get(): TParent | null;
+  set(data: Partial<TParent> | TParent | null): TParent | null;
+}
+
+export type BelongsToReference<TParent extends object = object> = BelongsToReferenceApi<TParent> & Partial<TParent>;
+
+export interface HasOneReferenceApi<TChild extends object = object> {
+  load(): Promise<TChild | null>;
+  get(): TChild | null;
+  set(data: Partial<TChild> | TChild | null): TChild | null;
+}
+
+export type HasOneReference<TChild extends object = object> = HasOneReferenceApi<TChild> & Partial<TChild>;
+
 export interface ManyToManyCollection<TTarget, TPivot extends object | undefined = undefined> {
   length: number;
   [Symbol.iterator](): Iterator<TTarget>;
@@ -111,24 +126,24 @@ export interface ManyToManyCollection<TTarget, TPivot extends object | undefined
   /** @internal Type-level marker for the related pivot entity */
   readonly __pivotType?: TPivot;
 }
-
-export type EntityInstance<
-  TTable extends TableDef,
-  TRow = InferRow<TTable>
-> = TRow & {
-  [K in keyof RelationMap<TTable>]: RelationWrapper<TTable['relations'][K]>;
-} & {
-  $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;
-};
-
-export type Primitive = string | number | boolean | Date | bigint | Buffer | null | undefined;
-
-type IsAny<T> = 0 extends (1 & T) ? true : false;
-
-export type SelectableKeys<T> = {
-  [K in keyof T]-?: IsAny<T[K]> extends true
-  ? never
-  : NonNullable<T[K]> extends Primitive
-  ? K
-  : never
-}[keyof T];
+
+export type EntityInstance<
+  TTable extends TableDef,
+  TRow = InferRow<TTable>
+> = TRow & {
+  [K in keyof RelationMap<TTable>]: RelationWrapper<TTable['relations'][K]>;
+} & {
+  $load<K extends keyof RelationMap<TTable>>(relation: K): Promise<RelationMap<TTable>[K]>;
+};
+
+export type Primitive = string | number | boolean | Date | bigint | Buffer | null | undefined;
+
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+
+export type SelectableKeys<T> = {
+  [K in keyof T]-?: IsAny<T[K]> extends true
+  ? never
+  : NonNullable<T[K]> extends Primitive
+  ? K
+  : never
+}[keyof T];

package/src/tree/tree-decorator.ts

@@ -5,16 +5,16 @@
  * Integrates with MetalORM's decorator entity system.
  */
 
-import type { TreeConfig } from './tree-types.js';
-import { resolveTreeConfig } from './tree-types.js';
-import { RelationKinds, belongsTo, hasMany } from '../schema/relation.js';
-import { addRelationMetadata, getEntityMetadata, type EntityConstructor } from '../orm/entity-metadata.js';
-import {
-  type DecoratorTreeMetadata,
-  getOrCreateMetadataBag,
-  readMetadataBag,
-  readMetadataBagFromConstructor
-} from '../decorators/decorator-metadata.js';
+import type { TreeConfig } from './tree-types.js';
+import { resolveTreeConfig } from './tree-types.js';
+import { RelationKinds, belongsTo, hasMany } from '../schema/relation.js';
+import { addRelationMetadata, getEntityMetadata, type EntityConstructor } from '../orm/entity-metadata.js';
+import {
+  type DecoratorTreeMetadata,
+  readMetadataBag,
+  readMetadataBagFromConstructor,
+  resolveFieldDecoratorInfo
+} from '../decorators/decorator-metadata.js';
 
 /**
  * Symbol key for storing tree metadata on entity classes.
@@ -81,25 +81,27 @@ export interface TreeDecoratorOptions {
  * }
  * ```
  */
-export function Tree(options: TreeDecoratorOptions = {}) {
-  return function <T extends abstract new (...args: unknown[]) => object>(
-    target: T,
-    context: ClassDecoratorContext<T>
-  ): T {
-    const config = resolveTreeConfig(options);
-    const metadataBag = readMetadataBag(context) ?? readMetadataBagFromConstructor(target);
-    const metadata: TreeMetadata = {
-      config,
-      parentProperty: metadataBag?.tree?.parentProperty,
-      childrenProperty: metadataBag?.tree?.childrenProperty
-    };
-    
-    setTreeMetadataOnClass(target, metadata);
-    registerTreeRelations(target as unknown as EntityConstructor, metadata);
-    
-    return target;
-  };
-}
+export function Tree(options: TreeDecoratorOptions = {}) {
+  return function <T extends abstract new (...args: unknown[]) => object>(
+    target: T,
+    context?: ClassDecoratorContext<T>
+  ): T {
+    const config = resolveTreeConfig(options);
+    const metadataBag = context
+      ? readMetadataBag(context) ?? readMetadataBagFromConstructor(target)
+      : readMetadataBagFromConstructor(target);
+    const metadata: TreeMetadata = {
+      config,
+      parentProperty: metadataBag?.tree?.parentProperty,
+      childrenProperty: metadataBag?.tree?.childrenProperty
+    };
+    
+    setTreeMetadataOnClass(target, metadata);
+    registerTreeRelations(target as unknown as EntityConstructor, metadata);
+    
+    return target;
+  };
+}
 
 /**
  * Decorator to mark a property as the parent relation in a tree entity.
@@ -110,22 +112,16 @@ export function Tree(options: TreeDecoratorOptions = {}) {
  * parent?: Category;
  * ```
  */
-export function TreeParent() {
-  return function <T, V>(
-    _value: undefined,
-    context: ClassFieldDecoratorContext<T, V>
-  ): void {
-    if (!context.name) {
-      throw new Error('TreeParent decorator requires a property name');
-    }
-    if (context.private) {
-      throw new Error('TreeParent decorator does not support private fields');
-    }
-    const propertyName = String(context.name);
-    const bag = getOrCreateMetadataBag(context);
-    bag.tree = { ...bag.tree, parentProperty: propertyName };
-  };
-}
+export function TreeParent() {
+  return function (targetOrValue: unknown, contextOrProperty: unknown): void {
+    const { propertyName, bag } = resolveFieldDecoratorInfo(
+      targetOrValue,
+      contextOrProperty,
+      'TreeParent'
+    );
+    bag.tree = { ...bag.tree, parentProperty: propertyName };
+  };
+}
 
 /**
  * Decorator to mark a property as the children relation in a tree entity.
@@ -136,54 +132,48 @@ export function TreeParent() {
  * children?: Category[];
  * ```
  */
-export function TreeChildren() {
-  return function <T, V>(
-    _value: undefined,
-    context: ClassFieldDecoratorContext<T, V>
-  ): void {
-    if (!context.name) {
-      throw new Error('TreeChildren decorator requires a property name');
-    }
-    if (context.private) {
-      throw new Error('TreeChildren decorator does not support private fields');
-    }
-    const propertyName = String(context.name);
-    const bag = getOrCreateMetadataBag(context);
-    bag.tree = { ...bag.tree, childrenProperty: propertyName };
-  };
-}
-
-/**
- * Synchronizes tree metadata + self-relations for entities using @Tree decorators.
- * Safe to call multiple times (idempotent).
- */
-export function syncTreeEntityMetadata(
-  ctor: EntityConstructor,
-  treeMetadata?: DecoratorTreeMetadata
-): void {
-  const current = getTreeMetadata(ctor);
-  if (!current) return;
-  const metadataBag = readMetadataBagFromConstructor(ctor);
-
-  const nextParentProperty =
-    treeMetadata?.parentProperty ?? metadataBag?.tree?.parentProperty ?? current.parentProperty;
-  const nextChildrenProperty =
-    treeMetadata?.childrenProperty ?? metadataBag?.tree?.childrenProperty ?? current.childrenProperty;
-
-  if (nextParentProperty !== current.parentProperty || nextChildrenProperty !== current.childrenProperty) {
-    setTreeMetadata(ctor, {
-      ...current,
-      parentProperty: nextParentProperty,
-      childrenProperty: nextChildrenProperty
-    });
-  }
-
-  registerTreeRelations(ctor, {
-    ...current,
-    parentProperty: nextParentProperty,
-    childrenProperty: nextChildrenProperty
-  });
-}
+export function TreeChildren() {
+  return function (targetOrValue: unknown, contextOrProperty: unknown): void {
+    const { propertyName, bag } = resolveFieldDecoratorInfo(
+      targetOrValue,
+      contextOrProperty,
+      'TreeChildren'
+    );
+    bag.tree = { ...bag.tree, childrenProperty: propertyName };
+  };
+}
+
+/**
+ * Synchronizes tree metadata + self-relations for entities using @Tree decorators.
+ * Safe to call multiple times (idempotent).
+ */
+export function syncTreeEntityMetadata(
+  ctor: EntityConstructor,
+  treeMetadata?: DecoratorTreeMetadata
+): void {
+  const current = getTreeMetadata(ctor);
+  if (!current) return;
+  const metadataBag = readMetadataBagFromConstructor(ctor);
+
+  const nextParentProperty =
+    treeMetadata?.parentProperty ?? metadataBag?.tree?.parentProperty ?? current.parentProperty;
+  const nextChildrenProperty =
+    treeMetadata?.childrenProperty ?? metadataBag?.tree?.childrenProperty ?? current.childrenProperty;
+
+  if (nextParentProperty !== current.parentProperty || nextChildrenProperty !== current.childrenProperty) {
+    setTreeMetadata(ctor, {
+      ...current,
+      parentProperty: nextParentProperty,
+      childrenProperty: nextChildrenProperty
+    });
+  }
+
+  registerTreeRelations(ctor, {
+    ...current,
+    parentProperty: nextParentProperty,
+    childrenProperty: nextChildrenProperty
+  });
+}
 
 /**
  * Gets tree metadata from an entity class.
@@ -197,50 +187,50 @@ export function getTreeMetadata(
 /**
  * Sets tree metadata on an entity class.
  */
-export function setTreeMetadata(
-  target: new (...args: unknown[]) => object,
-  metadata: TreeMetadata
-): void {
-  (target as unknown as Record<symbol, TreeMetadata>)[TREE_METADATA_KEY] = metadata;
-}
-
-const registerTreeRelations = (
-  target: EntityConstructor,
-  metadata: TreeMetadata
-): void => {
-  const entityMeta = getEntityMetadata(target);
-  if (!entityMeta) return;
-
-  if (metadata.parentProperty && !entityMeta.relations[metadata.parentProperty]) {
-    addRelationMetadata(target, metadata.parentProperty, {
-      kind: RelationKinds.BelongsTo,
-      propertyKey: metadata.parentProperty,
-      target: () => target,
-      foreignKey: metadata.config.parentKey
-    });
-    if (entityMeta.table && !entityMeta.table.relations[metadata.parentProperty]) {
-      entityMeta.table.relations[metadata.parentProperty] = belongsTo(
-        entityMeta.table,
-        metadata.config.parentKey
-      );
-    }
-  }
-
-  if (metadata.childrenProperty && !entityMeta.relations[metadata.childrenProperty]) {
-    addRelationMetadata(target, metadata.childrenProperty, {
-      kind: RelationKinds.HasMany,
-      propertyKey: metadata.childrenProperty,
-      target: () => target,
-      foreignKey: metadata.config.parentKey
-    });
-    if (entityMeta.table && !entityMeta.table.relations[metadata.childrenProperty]) {
-      entityMeta.table.relations[metadata.childrenProperty] = hasMany(
-        entityMeta.table,
-        metadata.config.parentKey
-      );
-    }
-  }
-};
+export function setTreeMetadata(
+  target: new (...args: unknown[]) => object,
+  metadata: TreeMetadata
+): void {
+  (target as unknown as Record<symbol, TreeMetadata>)[TREE_METADATA_KEY] = metadata;
+}
+
+const registerTreeRelations = (
+  target: EntityConstructor,
+  metadata: TreeMetadata
+): void => {
+  const entityMeta = getEntityMetadata(target);
+  if (!entityMeta) return;
+
+  if (metadata.parentProperty && !entityMeta.relations[metadata.parentProperty]) {
+    addRelationMetadata(target, metadata.parentProperty, {
+      kind: RelationKinds.BelongsTo,
+      propertyKey: metadata.parentProperty,
+      target: () => target,
+      foreignKey: metadata.config.parentKey
+    });
+    if (entityMeta.table && !entityMeta.table.relations[metadata.parentProperty]) {
+      entityMeta.table.relations[metadata.parentProperty] = belongsTo(
+        entityMeta.table,
+        metadata.config.parentKey
+      );
+    }
+  }
+
+  if (metadata.childrenProperty && !entityMeta.relations[metadata.childrenProperty]) {
+    addRelationMetadata(target, metadata.childrenProperty, {
+      kind: RelationKinds.HasMany,
+      propertyKey: metadata.childrenProperty,
+      target: () => target,
+      foreignKey: metadata.config.parentKey
+    });
+    if (entityMeta.table && !entityMeta.table.relations[metadata.childrenProperty]) {
+      entityMeta.table.relations[metadata.childrenProperty] = hasMany(
+        entityMeta.table,
+        metadata.config.parentKey
+      );
+    }
+  }
+};
 
 /**
  * Sets tree metadata on an entity class (internal, handles abstract classes).