Method matching

packages/core/src/entity/Collection.ts:177–213

Queries a subset of the collection items from the database with custom filtering, ordering, and pagination.

(options: MatchingOptions<T, P>)

  /** Queries a subset of the collection items from the database with custom filtering, ordering, and pagination. */
  async matching<TT extends T, P extends string = never>(options: MatchingOptions<T, P>): Promise<Loaded<TT, P>[]> {
    const em = this.getEntityManager()!;
    const { where, ctx, ...opts } = options;
    let items: Loaded<TT, P>[];

    if (this.property.kind === ReferenceKind.MANY_TO_MANY && em.getPlatform().usesPivotTable()) {
      // M:N via pivot table bypasses em.find(), so merge all 3 levels here
      opts.orderBy = QueryHelper.mergeOrderBy(opts.orderBy, this.property.orderBy, this.property.targetMeta?.orderBy);
      options.populate = (await em.preparePopulate(this.property.targetMeta!.class, options)) as any;
      const cond = (await em.applyFilters(
        this.property.targetMeta!.class,
        where,
        options.filters ?? {},
        'read',
      )) as FilterQuery<T>;
      const map = await em
        .getDriver()
        .loadFromPivotTable(this.property, [helper(this.owner).__primaryKeys], cond, opts.orderBy, ctx, options);
      items = map[helper(this.owner).getSerializedPrimaryKey()].map((item: EntityData<TT>) =>
        em.merge(this.property.targetMeta!.class, item, { convertCustomTypes: true }),
      ) as any;
      await em.populate(items, options.populate as any, options as any);
    } else {
      // em.find() merges entity-level orderBy, so only merge runtime + relation here
      opts.orderBy = QueryHelper.mergeOrderBy(opts.orderBy, this.property.orderBy);
      items = (await em.find(this.property.targetMeta!.class, this.createCondition(where), opts as any)) as any;
    }

    if (options.store) {
      this.hydrate(items, true);
      this.setSerializationContext(options);
      this.populated();
      this.#readonly = true;
    }

    return items;
  }

  /**
   * Returns the items (the collection must be initialized)