Class ScalarReference

packages/core/src/entity/Reference.ts:256–341

/** Wrapper for lazy scalar properties that provides on-demand loading from the database. */
export class ScalarReference<Value> {
  private entity?: object;
  #property?: string;
  #initialized: boolean;

  constructor(
    private value?: Value,
    initialized = value != null,
  ) {
    Object.defineProperty(this, scalarReferenceSymbol, { value: true, enumerable: false });
    this.#initialized = initialized;
  }

  /**
   * Ensures the underlying entity is loaded first (without reloading it if it already is loaded).
   * Returns either the whole entity, or the requested property.
   */
  async load(
    options?: Omit<LoadReferenceOptions<any, any>, 'populate' | 'fields' | 'exclude'>,
  ): Promise<Value | undefined> {
    const opts: Dictionary =
      typeof options === 'object' ? options : ({ prop: options } as LoadReferenceOptions<any, any>);

    if (!this.#initialized || opts.refresh) {
      if (this.entity == null || this.#property == null) {
        throw new Error('Cannot load scalar reference that is not bound to an entity property.');
      }

      await helper(this.entity).populate<any>([this.#property], opts);
    }

    return this.value;
  }

  /**
   * Ensures the underlying entity is loaded first (without reloading it if it already is loaded).
   * Returns the entity or throws an error just like `em.findOneOrFail()` (and respects the same config options).
   */
  async loadOrFail(
    options: Omit<LoadReferenceOrFailOptions<any, any>, 'populate' | 'fields' | 'exclude'> = {},
  ): Promise<Value> {
    const ret = await this.load(options);

    if (ret == null) {
      const wrapped = helper(this.entity!);
      options.failHandler ??= wrapped.__em!.config.get('findOneOrFailHandler');
      const entityName = this.entity!.constructor.name;
      throw NotFoundError.failedToLoadProperty(entityName, this.#property!, wrapped.getPrimaryKey());
    }

    return ret;
  }

  /** Sets the scalar value and marks the reference as initialized. */
  set(value: Value): void {
    this.value = value;
    this.#initialized = true;
  }