@loopback/repository 4.0.0-alpha.9 → 4.0.0

package/src/relations/has-many/has-many-through.repository-factory.ts

@@ -0,0 +1,121 @@
+// Copyright IBM Corp. 2020. All Rights Reserved.
+// Node module: @loopback/repository
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {
+  DataObject,
+  Entity,
+  EntityCrudRepository,
+  Getter,
+  HasManyDefinition,
+  InclusionResolver,
+} from '../..';
+import {
+  createTargetConstraintFromThrough,
+  createThroughConstraintFromSource,
+  createThroughConstraintFromTarget,
+  getTargetIdsFromTargetModels,
+  getTargetKeysFromThroughModels,
+  resolveHasManyThroughMetadata,
+} from './has-many-through.helpers';
+import {createHasManyThroughInclusionResolver} from './has-many-through.inclusion-resolver';
+import {
+  DefaultHasManyThroughRepository,
+  HasManyThroughRepository,
+} from './has-many-through.repository';
+
+/**
+ * a factory to generate hasManyThrough repository class.
+ *
+ * Warning: The hasManyThrough interface is experimental and is subject to change.
+ * If backwards-incompatible changes are made, a new major version may not be
+ * released.
+ */
+
+export type HasManyThroughRepositoryFactory<
+  TargetEntity extends Entity,
+  TargetID,
+  ThroughEntity extends Entity,
+  SourceID,
+> = {
+  (fkValue: SourceID): HasManyThroughRepository<
+    TargetEntity,
+    TargetID,
+    ThroughEntity
+  >;
+
+  /**
+   * Use `resolver` property to obtain an InclusionResolver for this relation.
+   */
+  inclusionResolver: InclusionResolver<Entity, TargetEntity>;
+};
+
+export function createHasManyThroughRepositoryFactory<
+  Target extends Entity,
+  TargetID,
+  Through extends Entity,
+  ThroughID,
+  SourceID,
+>(
+  relationMetadata: HasManyDefinition,
+  targetRepositoryGetter: Getter<EntityCrudRepository<Target, TargetID>>,
+  throughRepositoryGetter: Getter<EntityCrudRepository<Through, ThroughID>>,
+): HasManyThroughRepositoryFactory<Target, TargetID, Through, SourceID> {
+  const meta = resolveHasManyThroughMetadata(relationMetadata);
+  const result = function (fkValue: SourceID) {
+    function getTargetConstraintFromThroughModels(
+      throughInstances: Through[],
+    ): DataObject<Target> {
+      return createTargetConstraintFromThrough<Target, Through>(
+        meta,
+        throughInstances,
+      );
+    }
+    function getTargetKeys(throughInstances: Through[]): TargetID[] {
+      return getTargetKeysFromThroughModels(meta, throughInstances);
+    }
+    function getThroughConstraintFromSource(): DataObject<Through> {
+      const constraint: DataObject<Through> = createThroughConstraintFromSource<
+        Through,
+        SourceID
+      >(meta, fkValue);
+      return constraint;
+    }
+    function getTargetIds(targetInstances: Target[]): TargetID[] {
+      return getTargetIdsFromTargetModels(meta, targetInstances);
+    }
+    function getThroughConstraintFromTarget(
+      fkValues: TargetID[],
+    ): DataObject<Through> {
+      const constraint: DataObject<Through> = createThroughConstraintFromTarget<
+        Through,
+        TargetID
+      >(meta, fkValues);
+      return constraint;
+    }
+
+    return new DefaultHasManyThroughRepository<
+      Target,
+      TargetID,
+      EntityCrudRepository<Target, TargetID>,
+      Through,
+      ThroughID,
+      EntityCrudRepository<Through, ThroughID>
+    >(
+      targetRepositoryGetter,
+      throughRepositoryGetter,
+      getTargetConstraintFromThroughModels,
+      getTargetKeys,
+      getThroughConstraintFromSource,
+      getTargetIds,
+      getThroughConstraintFromTarget,
+    );
+  };
+  result.inclusionResolver = createHasManyThroughInclusionResolver(
+    meta,
+    throughRepositoryGetter,
+    targetRepositoryGetter,
+  );
+  return result;
+}

package/src/relations/has-many/has-many-through.repository.ts

@@ -0,0 +1,318 @@
+// Copyright IBM Corp. 2019,2020. All Rights Reserved.
+// Node module: @loopback/repository
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {
+  constrainDataObject,
+  constrainFilter,
+  constrainWhere,
+  constrainWhereOr,
+  Count,
+  DataObject,
+  Entity,
+  EntityCrudRepository,
+  Filter,
+  Getter,
+  Options,
+  Where,
+} from '../..';
+
+/**
+ * CRUD operations for a target repository of a HasManyThrough relation
+ *
+ * EXPERIMENTAL: This interface is not stable and may change in the near future.
+ * Backwards-incompatible changes may be introduced in semver-minor versions.
+ */
+export interface HasManyThroughRepository<
+  Target extends Entity,
+  TargetID,
+  Through extends Entity,
+> {
+  /**
+   * Create a target model instance
+   * @param targetModelData - The target model data
+   * @param options - Options for the operation
+   * @returns A promise which resolves to the newly created target model instance
+   */
+  create(
+    targetModelData: DataObject<Target>,
+    options?: Options & {
+      throughData?: DataObject<Through>;
+      throughOptions?: Options;
+    },
+  ): Promise<Target>;
+
+  /**
+   * Find target model instance(s)
+   * @param filter - A filter object for where, order, limit, etc.
+   * @param options - Options for the operation
+   * @returns A promise which resolves with the found target instance(s)
+   */
+  find(
+    filter?: Filter<Target>,
+    options?: Options & {
+      throughOptions?: Options;
+    },
+  ): Promise<Target[]>;
+
+  /**
+   * Delete multiple target model instances
+   * @param where - Instances within the where scope are deleted
+   * @param options
+   * @returns A promise which resolves the deleted target model instances
+   */
+  delete(
+    where?: Where<Target>,
+    options?: Options & {
+      throughOptions?: Options;
+    },
+  ): Promise<Count>;
+
+  /**
+   * Patch multiple target model instances
+   * @param dataObject - The fields and their new values to patch
+   * @param where - Instances within the where scope are patched
+   * @param options
+   * @returns A promise which resolves the patched target model instances
+   */
+  patch(
+    dataObject: DataObject<Target>,
+    where?: Where<Target>,
+    options?: Options & {
+      throughOptions?: Options;
+    },
+  ): Promise<Count>;
+
+  /**
+   * Creates a new many-to-many association to an existing target model instance
+   * @param targetModelId - The target model ID to link
+   * @param options
+   * @returns A promise which resolves to the linked target model instance
+   */
+  link(
+    targetModelId: TargetID,
+    options?: Options & {
+      throughData?: DataObject<Through>;
+      throughOptions?: Options;
+    },
+  ): Promise<void>;
+
+  /**
+   * Removes an association to an existing target model instance
+   * @param targetModelId - The target model to unlink
+   * @param options
+   * @returns A promise which resolves to null
+   */
+  unlink(
+    targetModelId: TargetID,
+    options?: Options & {
+      throughOptions?: Options;
+    },
+  ): Promise<void>;
+
+  /**
+   * Remove all association to an existing target model instance
+   * @param options
+   * @return A promise which resolves to void
+   */
+  unlinkAll(
+    options?: Options & {
+      throughOptions?: Options;
+    },
+  ): Promise<void>;
+}
+
+/**
+ * a class for CRUD operations for hasManyThrough relation.
+ *
+ * Warning: The hasManyThrough interface is experimental and is subject to change.
+ * If backwards-incompatible changes are made, a new major version may not be
+ * released.
+ */
+export class DefaultHasManyThroughRepository<
+  TargetEntity extends Entity,
+  TargetID,
+  TargetRepository extends EntityCrudRepository<TargetEntity, TargetID>,
+  ThroughEntity extends Entity,
+  ThroughID,
+  ThroughRepository extends EntityCrudRepository<ThroughEntity, ThroughID>,
+> implements HasManyThroughRepository<TargetEntity, TargetID, ThroughEntity>
+{
+  constructor(
+    public getTargetRepository: Getter<TargetRepository>,
+    public getThroughRepository: Getter<ThroughRepository>,
+    public getTargetConstraintFromThroughModels: (
+      throughInstances: ThroughEntity[],
+    ) => DataObject<TargetEntity>,
+    public getTargetKeys: (throughInstances: ThroughEntity[]) => TargetID[],
+    public getThroughConstraintFromSource: () => DataObject<ThroughEntity>,
+    public getTargetIds: (targetInstances: TargetEntity[]) => TargetID[],
+    public getThroughConstraintFromTarget: (
+      targetID: TargetID[],
+    ) => DataObject<ThroughEntity>,
+  ) {}
+
+  async create(
+    targetModelData: DataObject<TargetEntity>,
+    options?: Options & {
+      throughData?: DataObject<ThroughEntity>;
+      throughOptions?: Options;
+    },
+  ): Promise<TargetEntity> {
+    const targetRepository = await this.getTargetRepository();
+    const targetInstance = await targetRepository.create(
+      targetModelData,
+      options,
+    );
+    await this.link(targetInstance.getId(), options);
+    return targetInstance;
+  }
+
+  async find(
+    filter?: Filter<TargetEntity>,
+    options?: Options & {
+      throughOptions?: Options;
+    },
+  ): Promise<TargetEntity[]> {
+    const targetRepository = await this.getTargetRepository();
+    const throughRepository = await this.getThroughRepository();
+    const sourceConstraint = this.getThroughConstraintFromSource();
+    const throughInstances = await throughRepository.find(
+      constrainFilter(undefined, sourceConstraint),
+      options?.throughOptions,
+    );
+    const targetConstraint =
+      this.getTargetConstraintFromThroughModels(throughInstances);
+    return targetRepository.find(
+      constrainFilter(filter, targetConstraint),
+      options,
+    );
+  }
+
+  async delete(
+    where?: Where<TargetEntity>,
+    options?: Options & {
+      throughOptions?: Options;
+    },
+  ): Promise<Count> {
+    const targetRepository = await this.getTargetRepository();
+    const throughRepository = await this.getThroughRepository();
+    const sourceConstraint = this.getThroughConstraintFromSource();
+    const throughInstances = await throughRepository.find(
+      constrainFilter(undefined, sourceConstraint),
+      options?.throughOptions,
+    );
+    if (where) {
+      // only delete related through models
+      // TODO(Agnes): this performance can be improved by only fetching related data
+      // TODO: add target ids to the `where` constraint
+      const targets = await targetRepository.find({where});
+      const targetIds = this.getTargetIds(targets);
+      if (targetIds.length > 0) {
+        const targetConstraint = this.getThroughConstraintFromTarget(targetIds);
+        const constraints = {...targetConstraint, ...sourceConstraint};
+        await throughRepository.deleteAll(
+          constrainDataObject({}, constraints as DataObject<ThroughEntity>),
+          options?.throughOptions,
+        );
+      }
+    } else {
+      // otherwise, delete through models that relate to the sourceId
+      const targetFkValues = this.getTargetKeys(throughInstances);
+      // delete through instances that have the targets that are going to be deleted
+      const throughFkConstraint =
+        this.getThroughConstraintFromTarget(targetFkValues);
+      await throughRepository.deleteAll(
+        constrainWhereOr({}, [sourceConstraint, throughFkConstraint]),
+      );
+    }
+    // delete target(s)
+    const targetConstraint =
+      this.getTargetConstraintFromThroughModels(throughInstances);
+    return targetRepository.deleteAll(
+      constrainWhere(where, targetConstraint as Where<TargetEntity>),
+      options,
+    );
+  }
+  // only allows patch target instances for now
+  async patch(
+    dataObject: DataObject<TargetEntity>,
+    where?: Where<TargetEntity>,
+    options?: Options & {
+      throughOptions?: Options;
+    },
+  ): Promise<Count> {
+    const targetRepository = await this.getTargetRepository();
+    const throughRepository = await this.getThroughRepository();
+    const sourceConstraint = this.getThroughConstraintFromSource();
+    const throughInstances = await throughRepository.find(
+      constrainFilter(undefined, sourceConstraint),
+      options?.throughOptions,
+    );
+    const targetConstraint =
+      this.getTargetConstraintFromThroughModels(throughInstances);
+    return targetRepository.updateAll(
+      constrainDataObject(dataObject, targetConstraint),
+      constrainWhere(where, targetConstraint as Where<TargetEntity>),
+      options,
+    );
+  }
+
+  async link(
+    targetId: TargetID,
+    options?: Options & {
+      throughData?: DataObject<ThroughEntity>;
+      throughOptions?: Options;
+    },
+  ): Promise<void> {
+    const throughRepository = await this.getThroughRepository();
+    const sourceConstraint = this.getThroughConstraintFromSource();
+    const targetConstraint = this.getThroughConstraintFromTarget([targetId]);
+    const constraints = {...targetConstraint, ...sourceConstraint};
+    await throughRepository.create(
+      constrainDataObject(
+        options?.throughData ?? {},
+        constraints as DataObject<ThroughEntity>,
+      ),
+      options?.throughOptions,
+    );
+  }
+
+  async unlink(
+    targetId: TargetID,
+    options?: Options & {
+      throughOptions?: Options;
+    },
+  ): Promise<void> {
+    const throughRepository = await this.getThroughRepository();
+    const sourceConstraint = this.getThroughConstraintFromSource();
+    const targetConstraint = this.getThroughConstraintFromTarget([targetId]);
+    const constraints = {...targetConstraint, ...sourceConstraint};
+    await throughRepository.deleteAll(
+      constrainDataObject({}, constraints as DataObject<ThroughEntity>),
+      options?.throughOptions,
+    );
+  }
+
+  async unlinkAll(
+    options?: Options & {
+      throughOptions?: Options;
+    },
+  ): Promise<void> {
+    const throughRepository = await this.getThroughRepository();
+    const sourceConstraint = this.getThroughConstraintFromSource();
+    const throughInstances = await throughRepository.find(
+      constrainFilter(undefined, sourceConstraint),
+      options?.throughOptions,
+    );
+    const targetFkValues = this.getTargetKeys(throughInstances);
+    const targetConstraint =
+      this.getThroughConstraintFromTarget(targetFkValues);
+    const constraints = {...targetConstraint, ...sourceConstraint};
+    await throughRepository.deleteAll(
+      constrainDataObject({}, constraints as DataObject<ThroughEntity>),
+      options?.throughOptions,
+    );
+  }
+}

package/src/relations/has-many/has-many.decorator.ts

@@ -0,0 +1,38 @@
+// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Node module: @loopback/repository
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {Entity, EntityResolver} from '../../model';
+import {relation} from '../relation.decorator';
+import {HasManyDefinition, RelationType} from '../relation.types';
+
+/**
+ * Decorator for hasMany
+ * Calls property.array decorator underneath the hood and infers foreign key
+ * name from target model name unless explicitly specified
+ * @param targetResolver - Target model for hasMany relation
+ * @param definition - Optional metadata for setting up hasMany relation
+ * @returns A property decorator
+ */
+export function hasMany<T extends Entity>(
+  targetResolver: EntityResolver<T>,
+  definition?: Partial<HasManyDefinition>,
+) {
+  return function (decoratedTarget: object, key: string) {
+    const meta: HasManyDefinition = Object.assign(
+      // default values, can be customized by the caller
+      {name: key},
+      // properties provided by the caller
+      definition,
+      // properties enforced by the decorator
+      {
+        type: RelationType.hasMany,
+        targetsMany: true,
+        source: decoratedTarget.constructor,
+        target: targetResolver,
+      },
+    );
+    relation(meta)(decoratedTarget, key);
+  };
+}

package/src/relations/has-many/has-many.helpers.ts

@@ -0,0 +1,100 @@
+// Copyright IBM Corp. 2019,2020. All Rights Reserved.
+// Node module: @loopback/repository
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import debugFactory from 'debug';
+import {camelCase} from 'lodash';
+import {InvalidRelationError} from '../../errors';
+import {isTypeResolver} from '../../type-resolver';
+import {HasManyDefinition, RelationType} from '../relation.types';
+
+const debug = debugFactory('loopback:repository:relations:has-many:helpers');
+
+/**
+ * Relation definition with optional metadata (e.g. `keyTo`) filled in.
+ * @internal
+ */
+export type HasManyResolvedDefinition = HasManyDefinition & {
+  keyFrom: string;
+  keyTo: string;
+};
+
+/**
+ * Resolves given hasMany metadata if target is specified to be a resolver.
+ * Mainly used to infer what the `keyTo` property should be from the target's
+ * belongsTo metadata
+ * @param relationMeta - hasMany metadata to resolve
+ * @internal
+ */
+export function resolveHasManyMetadata(
+  relationMeta: HasManyDefinition,
+): HasManyResolvedDefinition {
+  // some checks and relationMeta.keyFrom are handled in here
+  relationMeta = resolveHasManyMetaHelper(relationMeta);
+
+  const targetModel = relationMeta.target();
+  const targetModelProperties = targetModel.definition?.properties;
+
+  const sourceModel = relationMeta.source;
+
+  if (relationMeta.keyTo && targetModelProperties[relationMeta.keyTo]) {
+    // The explicit cast is needed because of a limitation of type inference
+    return relationMeta as HasManyResolvedDefinition;
+  }
+
+  debug(
+    'Resolved model %s from given metadata: %o',
+    targetModel.modelName,
+    targetModel,
+  );
+  const defaultFkName = camelCase(sourceModel.modelName + '_id');
+  const hasDefaultFkProperty = targetModelProperties[defaultFkName];
+
+  if (!hasDefaultFkProperty) {
+    const reason = `target model ${targetModel.name} is missing definition of foreign key ${defaultFkName}`;
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  return Object.assign(relationMeta, {
+    keyTo: defaultFkName,
+  } as HasManyResolvedDefinition);
+}
+
+/**
+ * A helper to check relation type and the existence of the source/target models
+ * and set up keyFrom
+ * for HasMany(Through) relations
+ * @param relationMeta
+ *
+ * @returns relationMeta that has set up keyFrom
+ */
+export function resolveHasManyMetaHelper(
+  relationMeta: HasManyDefinition,
+): HasManyDefinition {
+  if ((relationMeta.type as RelationType) !== RelationType.hasMany) {
+    const reason = 'relation type must be HasMany';
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  if (!isTypeResolver(relationMeta.target)) {
+    const reason = 'target must be a type resolver';
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  const sourceModel = relationMeta.source;
+  if (!sourceModel || !sourceModel.modelName) {
+    const reason = 'source model must be defined';
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+  let keyFrom;
+  if (
+    relationMeta.keyFrom &&
+    relationMeta.source.definition.properties[relationMeta.keyFrom]
+  ) {
+    keyFrom = relationMeta.keyFrom;
+  } else {
+    keyFrom = sourceModel.getIdProperties()[0];
+  }
+  return Object.assign(relationMeta, {keyFrom}) as HasManyDefinition;
+}

package/src/relations/has-many/has-many.inclusion-resolver.ts

@@ -0,0 +1,88 @@
+// Copyright IBM Corp. 2019,2020. All Rights Reserved.
+// Node module: @loopback/repository
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {Filter, InclusionFilter} from '@loopback/filter';
+import debugFactory from 'debug';
+import {AnyObject, Options} from '../../common-types';
+import {Entity} from '../../model';
+import {EntityCrudRepository} from '../../repositories';
+import {
+  findByForeignKeys,
+  flattenTargetsOfOneToManyRelation,
+  StringKeyOf,
+} from '../relation.helpers';
+import {Getter, HasManyDefinition, InclusionResolver} from '../relation.types';
+import {resolveHasManyMetadata} from './has-many.helpers';
+
+const debug = debugFactory(
+  'loopback:repository:relations:has-many:inclusion-resolver',
+);
+
+/**
+ * Creates InclusionResolver for HasMany relation.
+ * Notice that this function only generates the inclusionResolver.
+ * It doesn't register it for the source repository.
+ *
+ * Notice: scope field for inclusion is not supported yet.
+ *
+ * @param meta - resolved metadata of the hasMany relation
+ * @param getTargetRepo - target repository i.e where related instances are
+ */
+export function createHasManyInclusionResolver<
+  Target extends Entity,
+  TargetID,
+  TargetRelations extends object,
+>(
+  meta: HasManyDefinition,
+  getTargetRepo: Getter<
+    EntityCrudRepository<Target, TargetID, TargetRelations>
+  >,
+): InclusionResolver<Entity, Target> {
+  const relationMeta = resolveHasManyMetadata(meta);
+
+  return async function fetchHasManyModels(
+    entities: Entity[],
+    inclusion: InclusionFilter,
+    options?: Options,
+  ): Promise<((Target & TargetRelations)[] | undefined)[]> {
+    if (!entities.length) return [];
+
+    debug('Fetching target models for entities:', entities);
+    debug('Relation metadata:', relationMeta);
+
+    const sourceKey = relationMeta.keyFrom;
+    const sourceIds = entities.map(e => (e as AnyObject)[sourceKey]);
+    const targetKey = relationMeta.keyTo as StringKeyOf<Target>;
+
+    debug('Parameters:', {sourceKey, sourceIds, targetKey});
+    debug(
+      'sourceId types',
+      sourceIds.map(i => typeof i),
+    );
+
+    const scope =
+      typeof inclusion === 'string' ? {} : (inclusion.scope as Filter<Target>);
+
+    const targetRepo = await getTargetRepo();
+    const targetsFound = await findByForeignKeys(
+      targetRepo,
+      targetKey,
+      sourceIds,
+      scope,
+      options,
+    );
+
+    debug('Targets found:', targetsFound);
+
+    const result = flattenTargetsOfOneToManyRelation(
+      sourceIds,
+      targetsFound,
+      targetKey,
+    );
+
+    debug('fetchHasManyModels result', result);
+    return result;
+  };
+}