Class Reference

packages/core/src/entity/Reference.ts:29–253

/** Wrapper around an entity that provides lazy loading capabilities and identity-preserving reference semantics. */
export class Reference<T extends object> {
  private property?: EntityProperty;

  constructor(private entity: T) {
    Object.defineProperty(this, referenceSymbol, { value: true, enumerable: false });
    this.set(entity);
    const meta = helper(this.entity).__meta;

    meta.primaryKeys.forEach(primaryKey => {
      Object.defineProperty(this, primaryKey, {
        get() {
          return this.entity[primaryKey];
        },
      });
    });

    if (meta.serializedPrimaryKey && meta.primaryKeys[0] !== meta.serializedPrimaryKey) {
      Object.defineProperty(this, meta.serializedPrimaryKey, {
        get() {
          return helper(this.entity).getSerializedPrimaryKey();
        },
      });
    }
  }

  /** Creates a Reference wrapper for the given entity, preserving identity if one already exists. */
  static create<T extends object>(entity: T | Ref<T>): Ref<T> {
    const unwrapped = Reference.unwrapReference(entity);
    const ref = helper(entity).toReference() as Reference<T>;

    if (unwrapped !== ref.unwrap()) {
      ref.set(unwrapped);
    }

    return ref as Ref<T>;
  }

  /** Creates a Reference wrapper for an entity identified by its primary key, wrapped in a Ref. */
  static createFromPK<T extends object>(
    entityType: EntityClass<T>,
    pk: Primary<T>,
    options?: { schema?: string },
  ): Ref<T> {
    const ref = this.createNakedFromPK(entityType, pk, options);
    return helper(ref)?.toReference() ?? ref;
  }

  /** Creates an uninitialized entity reference by primary key without wrapping it in a Reference. */
  static createNakedFromPK<T extends object>(
    entityType: EntityClass<T>,
    pk: Primary<T>,
    options?: { schema?: string },
  ): T {
    const factory = entityType.prototype.__factory as EntityFactory;

    if (!factory) {
      // this can happen only if `ref()` is used as a property initializer, and the value is important only for the
      // inference of defaults, so it's fine to return it directly without wrapping with `Reference` class