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

Description

Service to work with related, interlinked entities.

Metadata

Index

Methods

Methods

getEntityTypesReferencingType
getEntityTypesReferencingType(type: string)

Get all entity types whose schema includes fields referencing the given type.

e.g. given Child -> [Note, ChildSchoolRelation, ...]

Parameters :
Name Type Optional
type string No
Returns : literal type[]
getFieldsOfLinkedTypes
getFieldsOfLinkedTypes(entityType: EntityConstructor, dataType?: string)

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", …]] }]

Parameters :
Name Type Optional
entityType EntityConstructor No
dataType string Yes
Returns : LinkedTypeFields[]
itemReferencesId
itemReferencesId(item: unknown, refId: string, field?: EntitySchemaField)

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.

Parameters :
Name Type Optional
item unknown No
refId string No
field EntitySchemaField Yes
Returns : boolean
Async loadAllLinkingToEntity
loadAllLinkingToEntity(entity: Entity)

Find all entities that reference the given entity.

Parameters :
Name Type Optional Description
entity Entity No

The entity to find references to

Returns : Promise<literal type[]>

An array of objects containing an entity referencing the given entity and its specific fields that reference it

Async loadLinkingToEntities
loadLinkingToEntities<T>(referencedIds: string[], refType: EntityConstructor<T>, refProperty: string)
Type parameters :
  • T

Find the entities of one type that reference any of the given entities in one specific field, grouped by the entity they reference.

Unlike 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.

    Example :
       An entity referencing several of the given ids is listed for each of them.
       Empty if the user may not read the entity type.
Parameters :
Name Type Optional
referencedIds string[] No
refType EntityConstructor<T> No
refProperty string No
Returns : Promise<Map<string, T[]>>

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.

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 ""