Method preparePopulate

packages/core/src/EntityManager.ts:2874–3030

@internal

(
    entityName: EntityName<Entity>,
    options: Pick<
      FindOptions<Entity, any, any, any>,
      'populate' | 'strategy' | 'fields' | 'flags' | 'filters' | 'exclude' | 'populateHints'
    >,
    validate = true,
  )

  /** @internal */
  async preparePopulate<Entity extends object>(
    entityName: EntityName<Entity>,
    options: Pick<
      FindOptions<Entity, any, any, any>,
      'populate' | 'strategy' | 'fields' | 'flags' | 'filters' | 'exclude' | 'populateHints'
    >,
    validate = true,
  ): Promise<PopulateOptions<Entity>[]> {
    if (options.populate === false) {
      return [];
    }

    const meta = this.metadata.find(entityName)!;

    // infer populate hints from `fields` when present; merge with explicit `populate` if both are set.
    // `populateArray` is only kept when the entries are user-provided strings — when this method runs a
    // second time (e.g. from `lockAndPopulate`) the populate is already normalized and merging would be a no-op.
    const fields = options.fields ? this.buildFields(options.fields) : undefined;
    const populateArray =
      Array.isArray(options.populate) && options.populate.every(p => typeof p === 'string')
        ? (options.populate as string[])
        : undefined;
    const hasNestedFields = fields?.some(f => f.includes('.')) ?? false;
    const shouldInfer = fields !== undefined && options.populate === undefined;
    const shouldMerge =
      fields !== undefined && populateArray !== undefined && populateArray.length > 0 && hasNestedFields;

    if (shouldInfer || shouldMerge) {
      // we need to prune the `populate` hint from to-one relations, as partially loading them does not require their population, we want just the FK
      const pruneToOneRelations = (meta: EntityMetadata, fields: string[]): string[] => {
        const ret: string[] = [];

        for (let field of fields) {
          if (field === PopulatePath.ALL || field.startsWith(`${PopulatePath.ALL}.`)) {
            ret.push(
              ...meta.props
                .filter(prop => prop.lazy || [ReferenceKind.SCALAR, ReferenceKind.EMBEDDED].includes(prop.kind))
                .map(prop => prop.name),
            );
            continue;
          }

          field = field.split(':')[0];

          if (
            !field.includes('.') &&
            ![ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(meta.properties[field].kind)
          ) {
            ret.push(field);
            continue;
          }

          const parts = field.split('.');
          const key = parts.shift()!;

          if (parts.length === 0) {
            continue;
          }