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

Description

Handles loading and saving of data for any higher-level feature module. The EntityMapperService implicitly transforms objects from instances of Entity classes to the format to be written to the database and back - ensuring they you always receive instances of Entity subclasses, that you can simply treat them as normal javascript class instances without worrying about database persistance logic.

To understand more about how to use the Entity system in your own modules, refer to the developer documentation:

Metadata

Relationships

Depends on

No results matching.

Index

Methods

Methods

Public entityFromRawDoc
entityFromRawDoc(doc: Record)

Reconstruct an Entity instance from a raw serialized document (e.g. from a JSON export). The entity type is detected from the _id prefix of the document.

Parameters :
Name Type Optional
doc Record<string, unknown> No
Returns : Entity
Public Async findAllType
findAllType<T>(entityType: EntityConstructor<T> | string, filter: DataFilter<T>, sort?: { prop?: string; dir?: "asc" | "desc" })
Type parameters :
  • T

Like findType, but follows the cursor until every matching record is loaded.

CouchDB's _find returns only 25 documents when no limit is given, so the pages have to be requested explicitly. Only use this where the filter is expected to select a small share of the type - otherwise loadType is a single request.

Parameters :
Name Type Optional Description
entityType EntityConstructor<T> | string No

class for which results should be returned

filter DataFilter<T> No

a valid Mango Query Syntax query

sort { prop?: string; dir?: "asc" | "desc" } Yes

optional sort options

Returns : Promise<T[]>
Public Async findType
findType<T>(entityType: EntityConstructor<T> | string, filter: DataFilter<T>, page?: { limit: number; bookmark?: string }, sort?: { prop?: string; dir?: "asc" | "desc" })
Type parameters :
  • T

Similar to loadType but allows supports filtering, pagination and sorting.

Pagination uses a bookmark cursor (see Database.find): pass the bookmark returned by the previous call to continue after those results. It is forward-only - there is no way to jump back to an earlier page.

Parameters :
Name Type Optional Description
entityType EntityConstructor<T> | string No

class for which results should be returned

filter DataFilter<T> No

a valid Mango Query Syntax query

page { limit: number; bookmark?: string } Yes

optional pagination options

sort { prop?: string; dir?: "asc" | "desc" } Yes

optional sort options

Public Async load
load<T>(entityType: EntityConstructor<T> | string, id: string)
Type parameters :
  • T

Load an Entity from the database with the given id or the registered name of that class.

Parameters :
Name Type Optional Description
entityType EntityConstructor<T> | string No

Class that implements Entity, which is the type of Entity the results should be transformed to

id string No

The id of the entity to load

Returns : Promise<T>

A Promise resolving to an instance of entityType filled with its data.

Public Async loadType
loadType<T>(entityType: EntityConstructor<T> | string)
Type parameters :
  • T

Load all entities from the database of the given type (for example a list of entities of the type User). Important: Loading via the constructor is always preferred compared to loading via string. The latter doesn't allow strict type-checking and errors can only be discovered later

or the registered name of that class.

Parameters :
Name Type Optional Description
entityType EntityConstructor<T> | string No

Class that implements Entity, which is the type of Entity the results should be transformed to or the registered name of that class.

Returns : Promise<T[]>

A Promise resolving to an array of instances of entityType with the data of the loaded entities.

Public receiveUpdates
receiveUpdates<T>(entityType: EntityConstructor<T> | string)
Type parameters :
  • T

subscribe to this observable to receive updates whenever the state of an entity of a certain type changes. The updated-parameter will return the new entity as well as a field that describes the type of update (either "new", "update" or "remove").
This can be used in collaboration with the update(UpdatedEntity, Entities)-function to update a list of entities

Important: Loading via the constructor is always preferred compared to loading via string. The latter doesn't allow strict type-checking and errors can only be discovered later

Parameters :
Name Type Optional Description
entityType EntityConstructor<T> | string No

the type of the entity or the registered name of that class.

Public Async remove
remove<T>(entity: T)
Type parameters :
  • T

Delete an entity from the database.

Parameters :
Name Type Optional Description
entity T No

The entity to be deleted

Returns : Promise<any>
Protected resolveConstructor
resolveConstructor<T>(constructible: EntityConstructor<T> | string)
Type parameters :
  • T
Parameters :
Name Type Optional
constructible EntityConstructor<T> | string No
Public Async save
save<T>(entity: T, forceUpdate: boolean)
Type parameters :
  • T

Save an entity to the database after transforming it to its database representation. if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.

Parameters :
Name Type Optional Default value Description
entity T No

The entity to be saved

forceUpdate boolean No false

Optional flag whether any conflicting version in the database will be quietly overwritten. if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.

Returns : Promise<any>
Public Async saveAll
saveAll(entities: Entity[], forceUpdate: boolean)

Saves an array of entities that are possibly heterogeneous, i.e. the entity-type of all the entities does not have to be the same. This method should be chosen whenever a bigger number of entities needs to be saved if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.

Parameters :
Name Type Optional Default value Description
entities Entity[] No

The entities to save

forceUpdate boolean No false

Optional flag whether any conflicting version in the database will be quietly overwritten. if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.

Returns : Promise<any[]>
Protected setEntityMetadata
setEntityMetadata(entity: Entity)
Parameters :
Name Type Optional
entity Entity No
Returns : void
Public supportsFind
supportsFind<T>(entityType: EntityConstructor<T> | string)
Type parameters :
  • T

Whether this entity type's database can answer findType queries at all (see Database.supportsFind). Callers that only use a query as an optimisation check this and fall back to loadType.

Deliberately asks the database instance rather than the session type: a remote-only database (e.g. for audit records) serves queries in every session type, and the instance that will run the query is the only authority on whether it can.

Parameters :
Name Type Optional
entityType EntityConstructor<T> | string No
Returns : boolean
import { inject, Injectable } from "@angular/core";
import { Entity, EntityConstructor } from "../model/entity";
import { EmbeddedEntity } from "../model/embedded-entity";
import { EntitySchemaService } from "../schema/entity-schema.service";
import { Observable } from "rxjs";
import { UpdatedEntity } from "../model/entity-update";
import { EntityRegistry } from "../database-entity.decorator";
import { filter, map } from "rxjs/operators";
import { UpdateMetadata } from "../model/update-metadata";
import { CurrentUserSubject } from "../../session/current-user-subject";
import { DatabaseResolverService } from "../../database/database-resolver.service";
import {
  DatabaseDocChange,
  PartialBulkWriteError,
} from "../../database/database";
import { EntityAbility } from "../../permissions/ability/entity-ability";
import { EntityPermissionError } from "./entity-permission-error";
import { Logging } from "../../logging/logging.service";
import { EntityActionPermission } from "../../permissions/permission-types";
import { DataFilter } from "#src/app/core/filter/filters/filters";

/**
 * One page of entities, and the cursor to continue from.
 *
 * The cursor is opaque: a Mango bookmark from the database, or whatever a
 * paginated loader uses to mark its own position. Callers only pass it back.
 */
export interface EntityPage<T extends Entity> {
  records: T[];
  bookmark?: string;
}

/**
 * Number of documents fetched per request when paging through a complete result set
 * (see {@link EntityMapperService.findAllType}).
 */
export const FULL_LOAD_PAGE_SIZE = 500;

/**
 * Handles loading and saving of data for any higher-level feature module.
 * The EntityMapperService implicitly transforms objects from instances of Entity classes to the format to be written
 * to the database and back - ensuring they you always receive instances of {@link Entity} subclasses, that you can
 * simply treat them as normal javascript class instances without worrying about database persistance logic.
 *
 * To understand more about how to use the Entity system in your own modules, refer to the developer documentation:
 * - [Loading and Saving Data]{@link /additional-documentation/concepts/entity-system.html}
 * - [How to Create a new Entity Type]{@link /additional-documentation/how-to-guides/create-a-new-entity-type.html}
 */
@Injectable({ providedIn: "root" })
export class EntityMapperService {
  private dbResolver = inject(DatabaseResolverService);
  private entitySchemaService = inject(EntitySchemaService);
  private currentUser = inject(CurrentUserSubject);
  private registry = inject(EntityRegistry);
  private readonly ability = inject(EntityAbility, { optional: true });

  /**
   * Load an Entity from the database with the given id or the registered name of that class.
   *
   * @param entityType Class that implements Entity, which is the type of Entity the results should be transformed to
   * @param id The id of the entity to load
   * @returns A Promise resolving to an instance of entityType filled with its data.
   */
  public async load<T extends Entity>(
    entityType: EntityConstructor<T> | string,
    id: string,
  ): Promise<T> {
    const ctor = this.resolveConstructor(entityType);
    const entityId = Entity.createPrefixedId(ctor.ENTITY_TYPE, id);
    const result = await this.dbResolver
      .getDatabase(ctor.DATABASE)
      .get(entityId);
    return this.transformToEntityFormat(result, ctor);
  }

  /**
   * Load all entities from the database of the given type (for example a list of entities of the type User).
   * <em>Important:</em> Loading via the constructor is always preferred compared to loading via string. The latter
   * doesn't allow strict type-checking and errors can only be discovered later
   *
   * @param entityType Class that implements Entity, which is the type of Entity the results should be transformed to
   * or the registered name of that class.
   * @returns A Promise resolving to an array of instances of entityType with the data of the loaded entities.
   */
  public async loadType<T extends Entity>(
    entityType: EntityConstructor<T> | string,
  ): Promise<T[]> {
    const ctor = this.resolveConstructor(entityType);
    const records = await this.dbResolver
      .getDatabase(ctor.DATABASE)
      .getAll(ctor.ENTITY_TYPE + ":");
    return records.map((rec) => this.transformToEntityFormat(rec, ctor));
  }

  /**
   * Similar to loadType but allows supports filtering, pagination and sorting.
   *
   * Pagination uses a `bookmark` cursor (see {@link Database.find}): pass the
   * `bookmark` returned by the previous call to continue after those results.
   * It is forward-only - there is no way to jump back to an earlier page.
   *
   * @param entityType class for which results should be returned
   * @param filter a valid Mango Query Syntax query
   * @param page optional pagination options
   * @param sort optional sort options
   */
  public async findType<T extends Entity>(
    entityType: EntityConstructor<T> | string,
    filter: DataFilter<T>,
    page?: { limit: number; bookmark?: string },
    sort?: { prop?: string; dir?: "asc" | "desc" },
  ): Promise<EntityPage<T>> {
    const ctor = this.resolveConstructor(entityType);
    const result = await this.dbResolver
      .getDatabase(ctor.DATABASE)
      .find(ctor.ENTITY_TYPE, filter, page, sort);
    return {
      records: result.docs.map((rec) =>
        this.transformToEntityFormat(rec, ctor),
      ),
      bookmark: result.bookmark,
    };
  }

  /**
   * Whether this entity type's database can answer {@link findType} queries at all
   * (see {@link Database.supportsFind}). Callers that only use a query as an optimisation
   * check this and fall back to {@link loadType}.
   *
   * Deliberately asks the database instance rather than the session type: a remote-only
   * database (e.g. for audit records) serves queries in every session type, and the
   * instance that will run the query is the only authority on whether it can.
   */
  public supportsFind<T extends Entity>(
    entityType: EntityConstructor<T> | string,
  ): boolean {
    const ctor = this.resolveConstructor(entityType);
    return this.dbResolver.getDatabase(ctor.DATABASE).supportsFind();
  }

  /**
   * Like {@link findType}, but follows the cursor until every matching record is loaded.
   *
   * CouchDB's `_find` returns only 25 documents when no limit is given, so the pages have
   * to be requested explicitly. Only use this where the filter is expected to select a
   * small share of the type - otherwise {@link loadType} is a single request.
   *
   * @param entityType class for which results should be returned
   * @param filter a valid Mango Query Syntax query
   * @param sort optional sort options
   */
  public async findAllType<T extends Entity>(
    entityType: EntityConstructor<T> | string,
    filter: DataFilter<T>,
    sort?: { prop?: string; dir?: "asc" | "desc" },
  ): Promise<T[]> {
    const records: T[] = [];
    let bookmark: string | undefined;
    let page: T[];
    do {
      const previousBookmark = bookmark;
      const result = await this.findType(
        entityType,
        filter,
        { limit: FULL_LOAD_PAGE_SIZE, bookmark },
        sort,
      );
      page = result.records;
      bookmark = result.bookmark;
      records.push(...page);

      // a cursor that does not advance would loop forever
      if (!bookmark || bookmark === previousBookmark) {
        break;
      }
    } while (page.length === FULL_LOAD_PAGE_SIZE);

    return records;
  }

  /**
   * Reconstruct an Entity instance from a raw serialized document (e.g. from a JSON export).
   * The entity type is detected from the `_id` prefix of the document.
   */
  public entityFromRawDoc(doc: Record<string, unknown>): Entity {
    const typePrefix = (doc["_id"] as string)?.split(":")[0];
    const ctor = this.registry.get(typePrefix);
    return this.transformToEntityFormat(doc, ctor);
  }

  private transformToEntityFormat<T extends Entity>(
    record: any,
    ctor: EntityConstructor<T>,
  ): T {
    const entity = new ctor("");
    try {
      this.entitySchemaService.loadDataIntoEntity(entity, record);
    } catch (e) {
      // add _id information to error message
      e.message = `Could not transform entity "${record._id}": ${e.message}`;
      throw e;
    }
    return entity;
  }

  /**
   * subscribe to this observable to receive updates whenever the state of
   * an entity of a certain type changes.
   * The updated-parameter will return the new entity as well as a field that
   * describes the type of update (either "new", "update" or "remove").
   * <br>
   * This can be used in collaboration with the update(UpdatedEntity, Entities)-function
   * to update a list of entities
   * <br>
   *
   * <em>Important:</em> Loading via the constructor is always preferred compared to loading via string. The latter
   * doesn't allow strict type-checking and errors can only be discovered later
   * @param entityType the type of the entity or the registered name of that class.
   */
  public receiveUpdates<T extends Entity>(
    entityType: EntityConstructor<T> | string,
  ): Observable<UpdatedEntity<T>> {
    const ctor = this.resolveConstructor(entityType);
    const type = new ctor().getType();
    return this.dbResolver.changesFeed.pipe(
      filter((change) => change?._id.startsWith(type + ":")),
      map((doc: DatabaseDocChange) => {
        const entity = new ctor();
        this.entitySchemaService.loadDataIntoEntity(entity, doc);
        if (doc._deleted) {
          return { type: "remove", entity: entity };
        } else if (doc._rev.startsWith("1-")) {
          // This does not cover all the cases as docs with higher rev-number might be synchronized for the first time
          return { type: "new", entity: entity };
        } else {
          return { type: "update", entity: entity };
        }
      }),
    );
  }

  /**
   * Save an entity to the database after transforming it to its database representation.
   * @param entity The entity to be saved
   * @param forceUpdate Optional flag whether any conflicting version in the database will be quietly overwritten.
   *          if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.
   */
  public async save<T extends Entity>(
    entity: T,
    forceUpdate: boolean = false,
  ): Promise<any> {
    this.assertSavable(entity);
    this.assertPermission(entity);
    this.setEntityMetadata(entity);
    const rawData =
      this.entitySchemaService.transformEntityToDatabaseFormat(entity);
    const result = await this.dbResolver
      .getDatabase(entity.getConstructor().DATABASE)
      .put(rawData, forceUpdate);
    if (result?.ok) {
      entity._rev = result.rev;
    }
    return result;
  }

  /**
   * Saves an array of entities that are possibly heterogeneous, i.e.
   * the entity-type of all the entities does not have to be the same.
   * This method should be chosen whenever a bigger number of entities needs to be
   * saved
   * @param entities The entities to save
   * @param forceUpdate Optional flag whether any conflicting version in the database will be quietly overwritten.
   *          if a conflict occurs without the forceUpdate flag being set, the save will fail, rejecting the returned promise.
   */
  public async saveAll(
    entities: Entity[],
    forceUpdate: boolean = false,
  ): Promise<any[]> {
    if (!entities.length) {
      return [];
    }

    entities.forEach((e) => this.assertSavable(e));
    entities.forEach((e) => this.assertPermission(e));
    entities.forEach((e) => this.setEntityMetadata(e));

    const entitiesByDatabase = new Map<string, Entity[]>();
    entities.forEach((e) => {
      const databaseName = e.getConstructor().DATABASE;
      if (!entitiesByDatabase.has(databaseName)) {
        entitiesByDatabase.set(databaseName, []);
      }
      entitiesByDatabase.get(databaseName).push(e);
    });

    const savePromises = Array.from(entitiesByDatabase.entries()).map(
      ([databaseName, entitiesInDatabase]) => {
        const rawData = entitiesInDatabase.map((e) =>
          this.entitySchemaService.transformEntityToDatabaseFormat(e),
        );
        return this.dbResolver
          .getDatabase(databaseName)
          .putAll(rawData, forceUpdate)
          .then(
            (results) => {
              applyStoredRevisions(entitiesInDatabase, results);
              return results;
            },
            (error) => {
              // putAll rejects as soon as any document failed, but the others
              // are already stored (see Database.putAll). Without their new
              // revisions, the next save of those entities would conflict
              // with their own earlier write.
              if (Array.isArray(error)) {
                applyStoredRevisions(entitiesInDatabase, error);
              } else if (error instanceof PartialBulkWriteError) {
                applyStoredRevisions(entitiesInDatabase, error.storedResults);
              }
              throw error;
            },
          );
      },
    );

    const results = (await Promise.all(savePromises)).flat();
    return results;
  }

  /**
   * Delete an entity from the database.
   * @param entity The entity to be deleted
   */
  public async remove<T extends Entity>(entity: T): Promise<any> {
    this.assertPermission(entity, "delete");
    return this.dbResolver
      .getDatabase(entity.getConstructor().DATABASE)
      .remove(entity);
  }

  protected resolveConstructor<T extends Entity>(
    constructible: EntityConstructor<T> | string,
  ): EntityConstructor<T> | undefined {
    if (typeof constructible === "string") {
      return this.registry.get(constructible) as EntityConstructor<T>;
    } else {
      return constructible;
    }
  }

  private assertSavable(entity: Entity) {
    if (entity instanceof EmbeddedEntity) {
      // only a stand-in while editing an embedded entry, which is stored as part of its record
      throw new Error(
        "An embedded entry cannot be saved on its own, save the record holding it instead",
      );
    }
  }

  private assertPermission(entity: Entity, action?: EntityActionPermission) {
    if (!this.ability) {
      return;
    }
    if (!this.ability.initialized) {
      // known race during app startup; the server still enforces permissions
      Logging.debug(
        "Permission check skipped: ability not yet initialized",
        entity.getId(),
      );
      return;
    }
    const checkedAction = action ?? (entity.isNew ? "create" : "update");
    if (this.ability.cannot(checkedAction, entity)) {
      throw new EntityPermissionError(
        checkedAction,
        entity.getId(),
        entity.getType(),
      );
    }
  }

  protected setEntityMetadata(entity: Entity) {
    const currentUserId = this.currentUser.value?.getId();
    // allow PublicForm to inject a special created.by already beforehand
    const metadataBy =
      currentUserId ?? (entity.isNew ? entity.created?.by : undefined);
    const newMetadata = new UpdateMetadata(metadataBy);
    if (entity.isNew) {
      entity.created = newMetadata;
    }
    entity.updated = newMetadata;
  }
}

/**
 * Copy the revisions the database assigned back onto the saved entities.
 *
 * Matched by id rather than by position, so that a result missing from the
 * response cannot shift revisions onto other entities.
 */
function applyStoredRevisions(entities: Entity[], results: any[]) {
  const revisions = new Map(
    results.filter((r) => r?.ok).map((r) => [r.id, r.rev]),
  );
  for (const entity of entities) {
    const rev = revisions.get(entity.getId());
    if (rev) {
      entity._rev = rev;
    }
  }
}

/**
 * The records that were stored although the save as a whole was rejected.
 *
 * A rejected save reports what became of the records (see `Database.putAll`): the
 * results array when individual records failed, a {@link PartialBulkWriteError} when
 * the write stopped partway. Any other rejection means nothing was stored.
 */
export function storedRecordsOf(records: Entity[], error: unknown): Entity[] {
  let results: any[];
  if (Array.isArray(error)) {
    results = error;
  } else if (error instanceof PartialBulkWriteError) {
    results = error.storedResults;
  } else {
    return [];
  }

  const storedIds = new Set(
    results.filter((result) => result?.ok).map((result) => result.id),
  );
  return records.filter((entity) => storedIds.has(entity.getId()));
}

results matching ""

    No results matching ""