@loopback/repository 4.1.1 → 5.0.1

package/src/relations/references-many/references-many.accessor.ts

@@ -0,0 +1,76 @@
+// Copyright IBM Corp. and LoopBack contributors 2018,2019. 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 {DataObject} from '../../common-types';
+import {Entity} from '../../model';
+import {EntityCrudRepository} from '../../repositories/repository';
+import {
+  Getter,
+  InclusionResolver,
+  ReferencesManyDefinition,
+} from '../relation.types';
+import {resolveReferencesManyMetadata} from './references-many.helpers';
+import {createReferencesManyInclusionResolver} from './references-many.inclusion-resolver';
+import {DefaultReferencesManyRepository} from './references-many.repository';
+
+const debug = debugFactory(
+  'loopback:repository:relations:references-many:accessor',
+);
+
+export interface ReferencesManyAccessor<Target extends Entity, SourceId> {
+  /**
+   * Invoke the function to obtain HasManyRepository.
+   */
+  (sourceId: SourceId): Promise<Target>;
+
+  /**
+   * Use `resolver` property to obtain an InclusionResolver for this relation.
+   */
+  inclusionResolver: InclusionResolver<Entity, Target>;
+}
+
+/**
+ * Enforces a ReferencesMany constraint on a repository
+ */
+export function createReferencesManyAccessor<
+  Target extends Entity,
+  TargetIds,
+  Source extends Entity,
+  SourceId,
+>(
+  referencesManyMetadata: ReferencesManyDefinition,
+  targetRepoGetter: Getter<EntityCrudRepository<Target, TargetIds>>,
+  sourceRepository: EntityCrudRepository<Source, SourceId>,
+): ReferencesManyAccessor<Target, SourceId> {
+  const meta = resolveReferencesManyMetadata(referencesManyMetadata);
+  debug('Resolved ReferencesMany relation metadata: %o', meta);
+  const result: ReferencesManyAccessor<Target, SourceId> =
+    async function getTargetInstancesOfReferencesMany(sourceId: SourceId) {
+      const foreignKey = meta.keyFrom;
+      const primaryKey = meta.keyTo;
+      const sourceModel = await sourceRepository.findById(sourceId);
+      const foreignKeyValue = sourceModel[foreignKey as keyof Source];
+      // workaround to check referential integrity.
+      // should be removed once the memory connector ref integrity is done
+      // GH issue: https://github.com/loopbackio/loopback-next/issues/2333
+      if (!foreignKeyValue) {
+        return undefined as unknown as Target;
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const constraint: any = {[primaryKey]: foreignKeyValue};
+      const constrainedRepo = new DefaultReferencesManyRepository(
+        targetRepoGetter,
+        constraint as DataObject<Target>,
+      );
+      return constrainedRepo.get();
+    };
+
+  result.inclusionResolver = createReferencesManyInclusionResolver(
+    meta,
+    targetRepoGetter,
+  );
+  return result;
+}

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

@@ -0,0 +1,100 @@
+// Copyright IBM Corp. and LoopBack contributors 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 {DecoratorFactory, MetadataInspector} from '@loopback/core';
+import {property} from '../../decorators';
+import {Entity, EntityResolver, PropertyDefinition} from '../../model';
+import {relation} from '../relation.decorator';
+import {ReferencesManyDefinition, RelationType} from '../relation.types';
+
+/**
+ * Decorator for referencesMany
+ * @param targetResolver - A resolver function that returns the target model for
+ * a referencesMany relation
+ * @param definition - Optional metadata for setting up a referencesMany relation
+ * @param propertyDefinition - Optional metadata for setting up the property
+ * @returns A property decorator
+ */
+export function referencesMany<T extends Entity>(
+  targetResolver: EntityResolver<T>,
+  definition?: Partial<ReferencesManyDefinition>,
+  propertyDefinition?: Partial<PropertyDefinition>,
+) {
+  return function (decoratedTarget: Entity, decoratedKey: string) {
+    const propType =
+      MetadataInspector.getDesignTypeForProperty(
+        decoratedTarget,
+        decoratedKey,
+      ) ?? propertyDefinition?.type;
+
+    if (!propType) {
+      const fullPropName = DecoratorFactory.getTargetName(
+        decoratedTarget,
+        decoratedKey,
+      );
+      throw new Error(
+        `Cannot infer type of model property ${fullPropName} because ` +
+          'TypeScript compiler option `emitDecoratorMetadata` is not set. ' +
+          'Please enable `emitDecoratorMetadata` or use the third argument of ' +
+          '`@referencesMany` decorator to specify the property type explicitly.',
+      );
+    }
+
+    const sourceKeyType = MetadataInspector.getDesignTypeForProperty(
+      targetResolver().prototype,
+      definition?.keyTo ?? 'id',
+    );
+
+    if (!sourceKeyType) {
+      const fullPropName = DecoratorFactory.getTargetName(
+        targetResolver().prototype,
+        definition?.keyTo ?? 'id',
+      );
+      throw new Error(
+        `Cannot infer type of model property ${fullPropName} because ` +
+          'TypeScript compiler option `emitDecoratorMetadata` is not set. ' +
+          'Please enable `emitDecoratorMetadata` or use the second argument of ' +
+          '`@referencesMany` decorator to specify the property type explicitly.',
+      );
+    }
+
+    const propMeta: PropertyDefinition = Object.assign(
+      {},
+      // properties provided by the caller
+      propertyDefinition,
+      // properties enforced by the decorator
+      {
+        type: propType,
+        itemType: sourceKeyType,
+        // TODO(bajtos) Make the foreign key required once our REST API layer
+        // allows controller methods to exclude required properties
+        // required: true,
+      },
+    );
+    property(propMeta)(decoratedTarget, decoratedKey);
+
+    // @referencesMany() is typically decorating the foreign key property,
+    // e.g. customerIds. We need to strip the trailing "Ids" suffix from the name.
+    const relationName = decoratedKey.replace(/Ids$/, 's');
+
+    const meta: ReferencesManyDefinition = Object.assign(
+      // default values, can be customized by the caller
+      {
+        keyFrom: decoratedKey,
+        name: relationName,
+      },
+      // properties provided by the caller
+      definition,
+      // properties enforced by the decorator
+      {
+        type: RelationType.referencesMany,
+        targetsMany: true,
+        source: decoratedTarget.constructor,
+        target: targetResolver,
+      },
+    );
+    relation(meta)(decoratedTarget, decoratedKey);
+  };
+}

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

@@ -0,0 +1,82 @@
+// Copyright IBM Corp. and LoopBack contributors 2019. 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 {ReferencesManyDefinition, RelationType} from '../relation.types';
+
+const debug = debugFactory(
+  'loopback:repository:relations:references-many:helpers',
+);
+
+/**
+ * Relation definition with optional metadata (e.g. `keyTo`) filled in.
+ * @internal
+ */
+export type ReferencesManyResolvedDefinition = ReferencesManyDefinition & {
+  keyFrom: string;
+  keyTo: string;
+};
+
+/**
+ * Resolves given referencesMany metadata if target is specified to be a resolver.
+ * Mainly used to infer what the `keyTo` property should be from the target's
+ * property id metadata
+ * @param relationMeta - referencesMany metadata to resolve
+ * @internal
+ */
+export function resolveReferencesManyMetadata(
+  relationMeta: ReferencesManyDefinition,
+) {
+  if ((relationMeta.type as RelationType) !== RelationType.referencesMany) {
+    const reason = 'relation type must be ReferencesMany';
+    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);
+  }
+
+  const targetModel = relationMeta.target();
+  const targetName = targetModel.modelName;
+  debug('Resolved model %s from given metadata: %o', targetName, targetModel);
+
+  let keyFrom;
+  if (
+    relationMeta.keyFrom &&
+    relationMeta.source.definition.properties[relationMeta.keyFrom]
+  ) {
+    keyFrom = relationMeta.keyFrom;
+  } else {
+    keyFrom = camelCase(targetName + '_ids');
+  }
+
+  const targetProperties = targetModel.definition.properties;
+  debug('relation metadata from %o: %o', targetName, targetProperties);
+
+  if (relationMeta.keyTo && targetProperties[relationMeta.keyTo]) {
+    // The explicit cast is needed because of a limitation of type inference
+    return Object.assign(relationMeta, {
+      keyFrom,
+    }) as ReferencesManyResolvedDefinition;
+  }
+
+  const targetPrimaryKey = targetModel.definition.idProperties()[0];
+  if (!targetPrimaryKey) {
+    const reason = `${targetName} does not have any primary key (id property)`;
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  return Object.assign(relationMeta, {keyFrom, keyTo: targetPrimaryKey});
+}

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

@@ -0,0 +1,80 @@
+// Copyright IBM Corp. and LoopBack contributors 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 {AnyObject, Options} from '../../common-types';
+import {Entity} from '../../model';
+import {EntityCrudRepository} from '../../repositories';
+import {
+  deduplicate,
+  findByForeignKeys,
+  flattenTargetsOfOneToOneRelation,
+  StringKeyOf,
+} from '../relation.helpers';
+import {
+  Getter,
+  InclusionResolver,
+  ReferencesManyDefinition,
+} from '../relation.types';
+import {resolveReferencesManyMetadata} from './references-many.helpers';
+
+/**
+ * Creates InclusionResolver for ReferencesMany 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 ReferencesManyMetadata
+ * @param getTargetRepo - target repository i.e where related instances are
+ */
+export function createReferencesManyInclusionResolver<
+  Target extends Entity,
+  TargetIds,
+  TargetRelations extends object,
+>(
+  meta: ReferencesManyDefinition,
+  getTargetRepo: Getter<
+    EntityCrudRepository<Target, TargetIds, TargetRelations>
+  >,
+): InclusionResolver<Entity, Target> {
+  const relationMeta = resolveReferencesManyMetadata(meta);
+
+  return async function fetchIncludedModels(
+    entities: Entity[],
+    inclusion: InclusionFilter,
+    options?: Options,
+  ): Promise<(Target & TargetRelations)[][]> {
+    if (!entities.length) return [];
+
+    const sourceKey = relationMeta.keyFrom;
+    const sourceMap = entities.map(e => (e as AnyObject)[sourceKey]);
+    const sourceIds = sourceMap.flat();
+    const targetKey = relationMeta.keyTo as StringKeyOf<Target>;
+    const dedupedSourceIds = deduplicate(sourceIds);
+
+    const scope =
+      typeof inclusion === 'string' ? {} : (inclusion.scope as Filter<Target>);
+
+    const targetRepo = await getTargetRepo();
+    const targetsFound = await findByForeignKeys(
+      targetRepo,
+      targetKey,
+      dedupedSourceIds.filter(e => e),
+      scope,
+      options,
+    );
+
+    return sourceMap.map(chainIds => {
+      if (!chainIds) return [];
+      const targets = flattenTargetsOfOneToOneRelation(
+        chainIds,
+        targetsFound,
+        targetKey,
+      );
+      return targets.filter((v): v is Target & TargetRelations => v != null);
+    });
+  };
+}

package/src/relations/references-many/references-many.repository.ts

@@ -0,0 +1,55 @@
+// Copyright IBM Corp. and LoopBack contributors 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 {Getter} from '@loopback/core';
+import {DataObject, Options} from '../../common-types';
+import {EntityNotFoundError} from '../../errors';
+import {Entity} from '../../model';
+import {constrainFilter, EntityCrudRepository} from '../../repositories';
+
+/**
+ * CRUD operations for a target repository of a ReferencesMany relation
+ */
+export interface ReferencesManyRepository<Target extends Entity> {
+  /**
+   * Gets the target model instance
+   * @param options
+   * @returns A promise resolved with the target object or rejected
+   * with an EntityNotFoundError when target model instance was not found.
+   */
+  get(options?: Options): Promise<Target>;
+}
+
+export class DefaultReferencesManyRepository<
+  TargetEntity extends Entity,
+  TargetIds,
+  TargetRepository extends EntityCrudRepository<TargetEntity, TargetIds>,
+> implements ReferencesManyRepository<TargetEntity>
+{
+  /**
+   * Constructor of DefaultReferencesManyEntityCrudRepository
+   * @param getTargetRepository - the getter of the related target model repository instance
+   * @param constraint - the key value pair representing foreign key name to constrain
+   * the target repository instance
+   */
+  constructor(
+    public getTargetRepository: Getter<TargetRepository>,
+    public constraint: DataObject<TargetEntity>,
+  ) {}
+
+  async get(options?: Options): Promise<TargetEntity> {
+    const targetRepo = await this.getTargetRepository();
+    const result = await targetRepo.find(
+      constrainFilter(undefined, this.constraint),
+      options,
+    );
+    if (!result.length) {
+      // We don't have a direct access to the foreign key value here :(
+      const id = 'constraint ' + JSON.stringify(this.constraint);
+      throw new EntityNotFoundError(targetRepo.entityClass, id);
+    }
+    return result[0];
+  }
+}

package/src/relations/relation.decorator.ts

@@ -1,4 +1,4 @@
-// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Copyright IBM Corp. and LoopBack contributors 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
@@ -76,15 +76,3 @@ export function referencesOne(definition?: Object) {
     decoratorName: '@referencesOne',
   });
 }
-
-/**
- * Decorator for referencesMany
- * @param definition
- * @returns A property decorator
- */
-export function referencesMany(definition?: Object) {
-  const rel = Object.assign({type: RelationType.referencesMany}, definition);
-  return PropertyDecoratorFactory.createDecorator(RELATIONS_KEY, rel, {
-    decoratorName: '@referencesMany',
-  });
-}

package/src/relations/relation.filter.solver.ts

@@ -0,0 +1,56 @@
+import {Fields} from '@loopback/filter';
+import {cloneDeep} from 'lodash';
+
+export function includeFieldIfNot<MT>(
+  fields: Fields<MT> | undefined,
+  fieldToInclude: Extract<keyof MT, string>,
+): false | Fields<MT> {
+  if (!fields) {
+    return false;
+  } else if (Array.isArray(fields)) {
+    const fieldsCloned: {[P in keyof MT]?: boolean} = fields.reduce(
+      (prev, current) => ({...prev, [current]: true}),
+      {},
+    );
+    if (Object.keys(fieldsCloned).length > 0) {
+      if (fieldsCloned[fieldToInclude] === true) {
+        return false;
+      }
+      fieldsCloned[fieldToInclude] = true;
+      return fieldsCloned;
+    }
+    return false;
+  }
+
+  const fieldsCloned = cloneDeep(fields);
+  if (Object.keys(fieldsCloned).length > 0) {
+    let containsTrue = false;
+    for (const k in fieldsCloned) {
+      if (fieldsCloned[k] === true) {
+        containsTrue = true;
+      }
+    }
+    for (const k in fieldsCloned) {
+      if (k === fieldToInclude) {
+        if (fieldsCloned[k] === true) {
+          return false;
+        } else {
+          if (containsTrue) {
+            fieldsCloned[k] = true;
+          } else {
+            delete fieldsCloned[k];
+          }
+          return fieldsCloned;
+        }
+      }
+    }
+    if (containsTrue) {
+      fieldsCloned[fieldToInclude] = true;
+      return fieldsCloned;
+    } else {
+      return false;
+    }
+  } else {
+    return false;
+  }
+}

package/src/relations/relation.helpers.ts

@@ -1,4 +1,4 @@
-// Copyright IBM Corp. 2019,2020. All Rights Reserved.
+// Copyright IBM Corp. and LoopBack contributors 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
@@ -122,7 +122,22 @@ export async function includeRelatedModels<
   options?: Options,
 ): Promise<(T & Relations)[]> {
   entities = cloneDeep(entities);
-  include = cloneDeep(include);
+  if (options?.polymorphicType) {
+    include = include?.filter(inclusionFilter => {
+      if (typeof inclusionFilter === 'string') {
+        return true;
+      } else {
+        if (
+          inclusionFilter.targetType === undefined ||
+          inclusionFilter.targetType === options?.polymorphicType
+        ) {
+          return true;
+        }
+      }
+    });
+  } else {
+    include = cloneDeep(include);
+  }
   const result = entities as (T & Relations)[];
   if (!include) return result;
 

package/src/relations/relation.types.ts

@@ -1,4 +1,4 @@
-// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Copyright IBM Corp. and LoopBack contributors 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
@@ -74,6 +74,12 @@ export interface HasManyDefinition extends RelationDefinitionBase {
   keyTo?: string;
   keyFrom?: string;
 
+  /**
+   * With current architecture design, polymorphic type cannot be supported without through
+   * Consider using Source-hasMany->Through->hasOne->Target(polymorphic) for one-to-many relations
+   */
+  // polymorphic?: boolean | {discriminator: string};
+
   /**
    * Description of the through model of the hasManyThrough relation.
    *
@@ -107,6 +113,19 @@ export interface HasManyDefinition extends RelationDefinitionBase {
      * The foreign key of the target model defined in the through model, e.g. CategoryProductLink#productId
      */
     keyTo?: string;
+
+    /**
+     * The polymorphism of the target model. The discriminator is a key of *through* model.
+     * If the target model is not polymorphic, then the value should be left undefined or false;
+     * If the key on through model indicating the concrete class of the through instance is default
+     * i.e. camelCase(classNameOf(targetModelInstance)) + "Id"
+     * then the discriminator field can be undefined
+     *
+     * With current architecture design, polymorphic type cannot be supported without through
+     * Consider using Source hasMany Through hasOne Target(polymorphic)
+     * or Source hasMany Through belongsTo Target(polymorphic) for one-to-many relations
+     */
+    polymorphic?: boolean | {discriminator: string};
   };
 }
 
@@ -123,6 +142,14 @@ export interface BelongsToDefinition extends RelationDefinitionBase {
    * The primary key of the target model, e.g Customer#id.
    */
   keyTo?: string;
+  /**
+   * The polymorphism of the target model. The discriminator is a key of source model.
+   * If the target model is not polymorphic, then the value should be left undefined or false;
+   * If the key on source model indicating the concrete class of the target instance is default
+   * i.e. camelCase(classNameOf(throughModelInstance)) + "Id"
+   * Then the discriminator field can be undefined
+   */
+  polymorphic?: boolean | {discriminator: string};
 }
 
 export interface HasOneDefinition extends RelationDefinitionBase {
@@ -141,6 +168,29 @@ export interface HasOneDefinition extends RelationDefinitionBase {
    */
   keyTo?: string;
   keyFrom?: string;
+  /**
+   * The polymorphism of the target model. The discriminator is a key of source model.
+   * If the target model is not polymorphic, then the value should be left undefined or false;
+   * If the key on source model indicating the concrete class of the target instance is default
+   * i.e. camelCase(classNameOf(throughModelInstance)) + "Id"
+   * Then the discriminator field can be undefined
+   */
+  polymorphic?: boolean | {discriminator: string};
+}
+
+export interface ReferencesManyDefinition extends RelationDefinitionBase {
+  type: RelationType.referencesMany;
+  targetsMany: true;
+
+  /**
+   * keyTo: The foreign key used by the target model for this relation.
+   * keyFrom: The source key used by the source model for this relation.
+   *
+   * TODO(bajtos) Add relation description.
+   *
+   */
+  keyTo?: string;
+  keyFrom?: string;
 }
 
 /**
@@ -150,6 +200,7 @@ export type RelationMetadata =
   | HasManyDefinition
   | BelongsToDefinition
   | HasOneDefinition
+  | ReferencesManyDefinition
   // TODO(bajtos) add other relation types and remove RelationDefinitionBase once
   // all relation types are covered.
   | RelationDefinitionBase;

package/src/repositories/constraint-utils.ts

@@ -1,4 +1,4 @@
-// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Copyright IBM Corp. and LoopBack contributors 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

package/src/repositories/index.ts

@@ -1,10 +1,10 @@
-// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Copyright IBM Corp. and LoopBack contributors 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
 
+export * from './constraint-utils';
 export * from './kv.repository';
-export * from './legacy-juggler-bridge';
 export * from './kv.repository.bridge';
+export * from './legacy-juggler-bridge';
 export * from './repository';
-export * from './constraint-utils';

package/src/repositories/kv.repository.bridge.ts

@@ -1,4 +1,4 @@
-// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Copyright IBM Corp. and LoopBack contributors 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

package/src/repositories/kv.repository.ts

@@ -1,11 +1,11 @@
-// Copyright IBM Corp. 2018,2020. All Rights Reserved.
+// Copyright IBM Corp. and LoopBack contributors 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 {Repository} from './repository';
-import {Options, DataObject} from '../common-types';
+import {DataObject, Options} from '../common-types';
 import {Model} from '../model';
+import {Repository} from './repository';
 
 /**
  * Filter for keys