src/app/core/entity/entity-mapper/entity-relations.service.ts

Description

fields of an entity type that another type links to (see EntityRelationsService.getFieldsOfLinkedTypes)

Index

Properties

Properties

fields
fields: unknown[]
Type : unknown[]

the matching fields of the linked type, as [id, schema]

link
link: EntitySchemaField
Type : EntitySchemaField
linkedType
linkedType: EntityConstructor
Type : EntityConstructor
linkId
linkId: string
Type : string

id of the field linking to the type

import { inject, Injectable } from "@angular/core";
import { Entity, EntityConstructor } from "../model/entity";
import { asArray } from "../../../utils/asArray";
import { FormFieldConfig } from "../../common-components/entity-form/FormConfig";
import { EntityRegistry } from "../database-entity.decorator";
import { EntityMapperService } from "./entity-mapper.service";
import { EntitySchemaField } from "../schema/entity-schema-field";
import { EntitySchemaService } from "../schema/entity-schema.service";
import { getEmbeddedEntityReferenceFields } from "../schema/embedded-schema-field.util";
import { Logging } from "../../logging/logging.service";
import type { DataFilter } from "../../filter/filters/filters";
import { EntityDatatype } from "../../basic-datatypes/entity/entity.datatype";
import { DatabaseIndexingService } from "../database-indexing/database-indexing.service";
import { EntityAbility } from "../../permissions/ability/entity-ability";
import { SessionSubject } from "../../session/auth/session-info";

/** fields of an entity type that another type links to (see {@link EntityRelationsService.getFieldsOfLinkedTypes}) */
export interface LinkedTypeFields {
  /** id of the field linking to the type */
  linkId: string;
  link: EntitySchemaField;
  linkedType: EntityConstructor;
  /** the matching fields of the linked type, as [id, schema] */
  fields: [string, EntitySchemaField][];
}

/** the property of an entity that a reference index can be created for */
type IndexedProperty = Parameters<
  DatabaseIndexingService["generateIndexOnProperty"]
>[2];

/**
 * Service to work with related, interlinked entities.
 */
@Injectable({
  providedIn: "root",
})
export class EntityRelationsService {
  private readonly entityMapper = inject(EntityMapperService);
  private readonly entityRegistry = inject(EntityRegistry);
  private readonly schemaService = inject(EntitySchemaService);
  private readonly dbIndexing = inject(DatabaseIndexingService);
  private readonly ability = inject(EntityAbility, { optional: true });
  private readonly sessionInfo = inject(SessionSubject, { optional: true });

  /** ids of the reference indexes that were already requested in this session */
  private readonly requestedReferenceIndexes = new Set<string>();

  /**
   * Get all entity types whose schema includes fields referencing the given type.
   *
   * e.g. given Child -> [Note, ChildSchoolRelation, ...]
   * @param type
   */
  getEntityTypesReferencingType(type: string): {
    entityType: EntityConstructor;
    referencingProperties: FormFieldConfig[];
  }[] {
    const referencingTypes = [];
    for (const t of this.entityRegistry.values()) {
      for (const [key, field] of t.schema.entries()) {
        if (this.fieldReferencesType(field, type)) {
          let refType = referencingTypes.find((e) => e.entityType === t);
          if (!refType) {
            refType = { entityType: t, referencingProperties: [] };
            referencingTypes.push(refType);
          }

          refType.referencingProperties.push({ ...field, id: key });
        }
      }
    }
    return referencingTypes;
  }

  /**
   * Get the fields (of the given data type, if any) in each entity type that the given type links to,
   * along with the field linking to it.
   *
   * e.g. given Child and "date-range" -> [{ linkId: "projectSchool", linkedType: School, fields: [["dateRangeField", …]] }]
   */
  getFieldsOfLinkedTypes(
    entityType: EntityConstructor,
    dataType?: string,
  ): LinkedTypeFields[] {
    return Array.from(entityType.schema)
      .filter(([, link]) => link.dataType === EntityDatatype.dataType)
      .flatMap(([linkId, link]) =>
        asArray(link.additional ?? [])
          .filter((typeId) => this.entityRegistry.has(typeId))
          .map((typeId) => {
            const linkedType = this.entityRegistry.get(typeId);
            return {
              linkId,
              link,
              linkedType,
              fields: Array.from(linkedType.schema).filter(
                ([, field]) => !dataType || field.dataType === dataType,
              ),
            };
          }),
      );
  }

  /**
   * Check whether a schema field references the given entity type,
   * including nested references inside embedded schemas (e.g. attendance fields).
   */
  private fieldReferencesType(field: EntitySchemaField, type: string): boolean {
    if (asArray(field.additional).includes(type)) {
      return true;
    }

    return getEmbeddedEntityReferenceFields(this.schemaService, field).some(
      ([, inner]) => asArray(inner.additional).includes(type),
    );
  }

  /**
   * Find all entities that reference the given entity.
   * @param entity The entity to find references to
   * @returns An array of objects containing an entity referencing the given entity and its specific fields that reference it
   */
  async loadAllLinkingToEntity(
    entity: Entity,
  ): Promise<{ entity: Entity; fields: FormFieldConfig[] }[]> {
    const linkedEntities = [];

    const entityTypesWithReferences = this.getEntityTypesReferencingType(
      entity.getType(),
    );

    for (const refType of entityTypesWithReferences) {
      const referencedEntities = await this.loadLinkedEntitiesOfType(
        entity,
        refType.entityType,
        refType.referencingProperties,
      );
      linkedEntities.push(...referencedEntities);
    }

    return linkedEntities;
  }

  /**
   * Find the entities of one type that reference any of the given entities in one specific field,
   * grouped by the entity they reference.
   *
   * Unlike {@link loadAllLinkingToEntity} this loads a single, known relationship
   * (e.g. the "Task" records whose `parentTask` is one of the given records)
   * and does so for many referenced entities at once.
   * The field can be a plain entity-reference field or hold embedded objects
   * with references (e.g. the participants of attendance items).
   *
   * Only the records needed are loaded, where possible:
   * - through a database query, if the database answers queries (online-only)
   *   (all records of the type are loaded instead if the query fails);
   * - through a database index of the field, on a local database
   *   (all records of the type are loaded instead if the index cannot be used);
   * - all records of the type for a visitor without an account (public forms),
   *   whom the server does not let query indexes.
   *
   * @returns A map of each referenced id that has any entity linking to it, to these linking entities.
   *          An entity referencing several of the given ids is listed for each of them.
   *          Empty if the user may not read the entity type.
   */
  async loadLinkingToEntities<T extends Entity = Entity>(
    referencedIds: string[],
    refType: EntityConstructor<T>,
    refProperty: string,
  ): Promise<Map<string, T[]>> {
    const ids = new Set(referencedIds);
    const field = refType.schema.get(refProperty);
    if (!field || ids.size === 0 || !this.canRead(refType)) {
      return new Map();
    }

    const candidates = await this.loadCandidatesForField([...ids], refType, {
      ...field,
      id: refProperty,
    });
    const innerKeys = this.innerReferenceKeys(field);
    return groupByReferencedId(candidates, ids, (entity) =>
      referencedIdsIn(entity[refProperty], innerKeys),
    );
  }

  /**
   * The records of the type that may reference one of the ids in the one field
   * (like {@link loadCandidates} for several fields, see {@link loadLinkingToEntities} for how they are loaded).
   */
  private async loadCandidatesForField<T extends Entity>(
    ids: string[],
    refType: EntityConstructor<T>,
    field: FormFieldConfig,
  ): Promise<T[]> {
    if (this.sessionInfo && !this.sessionInfo.value) {
      return this.entityMapper.loadType(refType);
    }
    if (
      !this.entityMapper.supportsFind(refType) &&
      field.dataType === EntityDatatype.dataType
    ) {
      return this.loadThroughReferenceIndex(refType, field.id, ids);
    }
    return this.loadCandidates(ids, refType, [field]);
  }

  /**
   * The records referencing one of the ids through the reference index of the field
   * (created on first use), or all records of the type if the index cannot be used.
   */
  private async loadThroughReferenceIndex<T extends Entity>(
    refType: EntityConstructor<T>,
    property: string,
    ids: string[],
  ): Promise<T[]> {
    const indexId = `linking_${refType.ENTITY_TYPE}_${property}`;
    let records: T[];
    try {
      if (!this.requestedReferenceIndexes.has(indexId)) {
        this.requestedReferenceIndexes.add(indexId);
        await this.dbIndexing.generateIndexOnProperty(
          indexId,
          refType,
          property as IndexedProperty,
        );
      }
      records = await this.dbIndexing.queryIndexDocs(
        refType,
        `${indexId}/by_${property}`,
        { keys: ids },
      );
    } catch (error) {
      // only a local database gets here, where the index should always work
      Logging.warn(
        "EntityRelationsService: Could not use the index of linked records, loading all records of the type instead",
        error,
        { entityType: refType.ENTITY_TYPE, field: property },
      );
      return this.entityMapper.loadType(refType);
    }
    // a record referencing several of the ids is returned once for each of them
    return [...new Map(records.map((r) => [r.getId(), r])).values()];
  }

  /** The inner reference properties of an embedded field, empty for other fields. */
  private innerReferenceKeys(field: EntitySchemaField | undefined): string[] {
    if (field?.dataType === EntityDatatype.dataType) {
      return [];
    }
    return getEmbeddedEntityReferenceFields(this.schemaService, field).map(
      ([key]) => key,
    );
  }

  /**
   * Whether the user may read records of the type.
   * Until the permissions are loaded, this is not known (the server checks them anyway).
   */
  private canRead(entityType: EntityConstructor): boolean {
    return !this.ability?.initialized || this.ability.can("read", entityType);
  }

  /**
   * Search through all entities of the given type and find those that reference the given entity.
   * @param primaryEntity The entity to which the other entities include a reference
   * @param refType The entity type of the entities to search for references to primaryEntity
   * @param refProperties The fields of the refType entities that may contain a reference (based on the refType's schema)
   * @private
   */
  private async loadLinkedEntitiesOfType(
    primaryEntity: Entity,
    refType: EntityConstructor,
    refProperties: FormFieldConfig[],
  ) {
    const entities = await this.loadCandidates(
      [primaryEntity.getId()],
      refType,
      refProperties,
    );

    const affectedEntities = entities
      .map((entity) => ({
        entity,
        fields: this.fieldsIncludingId(
          entity,
          primaryEntity.getId(),
          refProperties,
        ),
      }))
      .filter((affected) => affected.fields.length > 0);

    return affectedEntities;
  }

  /**
   * The records of the given type that may reference one of the given ids.
   *
   * Where every referencing property can express itself as a database query, this loads
   * only the matching records instead of the whole entity type - which is what keeps a
   * merge or a cascading delete from transferring the entire database.
   *
   * All-or-nothing per type: a full load already contains every property's matches, so
   * combining it with queries for the remaining properties would transfer the same
   * documents twice. The caller post-filters the result either way, so a query that
   * matches too much is harmless. If the query fails, the whole type is loaded as well.
   */
  private async loadCandidates<T extends Entity>(
    referencedIds: string[],
    refType: EntityConstructor<T>,
    refProperties: FormFieldConfig[],
  ): Promise<T[]> {
    if (!this.entityMapper.supportsFind(refType)) {
      // a local database answers no queries, but its full load is cheap
      return this.entityMapper.loadType(refType);
    }

    const conditions: DataFilter<any>[] = [];
    for (const refProperty of refProperties) {
      const datatype = this.schemaService.getDatatypeOrDefault(
        refProperty.dataType,
      );
      const selectors = datatype.getReferenceSelector(
        refProperty.id,
        refProperty,
        referencedIds,
      );
      if (!selectors?.length) {
        Logging.debug(
          "loading all records of an entity type because a referencing field cannot be queried",
          { entityType: refType.ENTITY_TYPE, field: refProperty.id },
        );
        return this.entityMapper.loadType(refType);
      }
      conditions.push(...selectors);
    }

    if (conditions.length === 0) {
      return [];
    }
    try {
      return await this.entityMapper.findAllType(refType, { $or: conditions });
    } catch (error) {
      // a failure of the user's environment (e.g. offline) is logged at debug by Logging itself
      Logging.warn(
        "EntityRelationsService: Could not query the linked records, loading all records of the type instead",
        error,
        {
          entityType: refType.ENTITY_TYPE,
          fields: refProperties.map((p) => p.id),
        },
      );
      return this.entityMapper.loadType(refType);
    }
  }

  /**
   * Check whether a single value (a plain ID string or an embedded object)
   * references the given entity ID.
   *
   * When the `field` is an embedded schema field, only its inner properties
   * holding entity references (`dataType: "entity"`) are inspected.
   * Without such schema info the function falls back to checking all object values.
   */
  itemReferencesId(
    item: unknown,
    refId: string,
    field?: EntitySchemaField,
  ): boolean {
    return referencedIdsIn(item, this.innerReferenceKeys(field)).includes(
      refId,
    );
  }

  /**
   * Return the fields of entity that contain the given refId.
   * If there is no such referenced ID, the array will be empty.
   * @param entity
   * @param refId
   * @param relevantFields The entity fields to check for the refId
   */
  private fieldsIncludingId(
    entity: Entity,
    refId: string,
    relevantFields: FormFieldConfig[],
  ): FormFieldConfig[] {
    return relevantFields.filter((field) =>
      referencedIdsIn(
        entity[field.id],
        this.innerReferenceKeys(field),
      ).includes(refId),
    );
  }
}

/**
 * The ids a field value references: the plain id(s), or for embedded objects the ids
 * in their inner reference properties (all their values, if `innerKeys` is empty).
 */
function referencedIdsIn(value: unknown, innerKeys: string[]): unknown[] {
  return asArray(value).flatMap((item) => {
    if (typeof item !== "object" || item === null) {
      return [item];
    }
    return innerKeys.length > 0
      ? innerKeys.flatMap((key) => asArray(item[key]))
      : Object.values(item);
  });
}

/**
 * Group the entities by which of the given ids they reference.
 * An entity referencing several of the ids is listed for each of them.
 */
function groupByReferencedId<T extends Entity>(
  entities: T[],
  ids: Set<string>,
  referencedIdsOf: (entity: T) => unknown[],
): Map<string, T[]> {
  const groups = new Map<string, T[]>();
  for (const entity of entities) {
    // a Set, so that an id referenced twice (e.g. by two embedded items) counts only once
    for (const id of new Set<unknown>(referencedIdsOf(entity))) {
      if (typeof id === "string" && ids.has(id)) {
        if (!groups.has(id)) {
          groups.set(id, []);
        }
        groups.get(id).push(entity);
      }
    }
  }
  return groups;
}

results matching ""

    No results matching ""