feat(repository): introduce hasmany relation decorator inference

- Implement `hasMany` decorator which takes the target model class and infers
  the relation metadata and return type as an array of the target model
  instances
- store relation metadata on model definition
- modify the function returned by `hasManyRepositoryFactory` function to only
  take in value of the PK/FK constraint instead of a key value pair for the PK
  (`{id: 5}` -> `5`}
- create a protected function in DefaultEntityCrudRepository which calls
  `hasManyRepositoryFactory` using the metadata stored by `hasMany` decorator on
  the source model definition and returns a constrained version of the target
  repository

Co-authored-by: Kyu Shim <kyu.shim@ibm.com>

Author: 2 people

packages/repository/package.json

@@ -25,13 +25,13 @@
     "@loopback/build": "^0.6.11",
     "@loopback/testlab": "^0.10.10",
     "@types/lodash": "^4.14.108",
-    "@types/node": "^10.1.1",
-    "lodash": "^4.17.10"
+    "@types/node": "^10.1.1"
   },
   "dependencies": {
     "@loopback/context": "^0.11.9",
     "@loopback/core": "^0.10.1",
     "@loopback/dist-util": "^0.3.3",
+    "lodash": "^4.17.10",
     "loopback-datasource-juggler": "^3.20.2"
   },
   "files": [

packages/repository/src/decorators/model.decorator.ts

@@ -15,6 +15,7 @@ import {
   ModelDefinitionSyntax,
   PropertyDefinition,
 } from '../model';
+import {RELATIONS_KEY, RelationDefinitionBase} from './relation.decorator';
 
 export const MODEL_KEY = MetadataAccessor.create<
   Partial<ModelDefinitionSyntax>,
@@ -30,6 +31,7 @@ export const MODEL_WITH_PROPERTIES_KEY = MetadataAccessor.create<
 >('loopback:model-and-properties');
 
 export type PropertyMap = MetadataMap<PropertyDefinition>;
+export type RelationMap = MetadataMap<RelationDefinitionBase>;
 
 // tslint:disable:no-any
 
@@ -73,6 +75,13 @@ export function model(definition?: Partial<ModelDefinitionSyntax>) {
     }
 
     target.definition = modelDef;
+
+    const relationMap: RelationMap =
+      MetadataInspector.getAllPropertyMetadata(
+        RELATIONS_KEY,
+        target.prototype,
+      ) || {};
+    target.definition.relations = relationMap;
   };
 }
 

packages/repository/src/decorators/relation.decorator.ts

@@ -5,8 +5,9 @@
 
 import {Class} from '../common-types';
 import {Entity} from '../model';
-
 import {PropertyDecoratorFactory} from '@loopback/context';
+import {property} from './model.decorator';
+import {camelCase} from 'lodash';
 
 // tslint:disable:no-any
 
@@ -28,6 +29,15 @@ export class RelationMetadata {
   as: string;
 }
 
+export interface RelationDefinitionBase {
+  type: RelationType;
+}
+
+export interface HasManyDefinition extends RelationDefinitionBase {
+  type: RelationType.hasMany;
+  keyTo: string;
+}
+
 /**
  * Decorator for relations
  * @param definition
@@ -61,12 +71,44 @@ export function hasOne(definition?: Object) {
 
 /**
  * Decorator for hasMany
- * @param definition
+ * Calls property.array decorator underneath the hood and infers foreign key
+ * name from target model name unless explicitly specified
+ * @param targetModel Target model for hasMany relation
+ * @param definition Optional metadata for setting up hasMany relation
  * @returns {(target:any, key:string)}
  */
-export function hasMany(definition?: Object) {
-  const rel = Object.assign({type: RelationType.hasMany}, definition);
-  return PropertyDecoratorFactory.createDecorator(RELATIONS_KEY, rel);
+export function hasMany<T extends typeof Entity>(
+  targetModel: T,
+  definition?: Partial<HasManyDefinition>,
+) {
+  // todo(shimks): extract out common logic (such as @property.array) to
+  // @relation
+  return function(target: Object, key: string) {
+    property.array(targetModel)(target, key);
+
+    const defaultFkName = camelCase(target.constructor.name + '_id');
+    const hasKeyTo = definition && definition.keyTo;
+    const hasDefaultFkProperty =
+      targetModel.definition &&
+      targetModel.definition.properties &&
+      targetModel.definition.properties[defaultFkName];
+    if (!(hasKeyTo || hasDefaultFkProperty)) {
+      // note(shimks): should we also check for the existence of explicitly
+      // given foreign key name on the juggler definition?
+      throw new Error(
+        `foreign key ${defaultFkName} not found on ${
+          targetModel.name
+        } model's juggler definition`,
+      );
+    }
+    const meta = {keyTo: defaultFkName};
+    Object.assign(meta, definition, {type: RelationType.hasMany});
+
+    PropertyDecoratorFactory.createDecorator(
+      RELATIONS_KEY,
+      meta as HasManyDefinition,
+    )(target, key);
+  };
 }
 
 /**

packages/repository/src/model.ts

@@ -5,6 +5,7 @@
 
 import {Options, AnyObject, DataObject} from './common-types';
 import {Type} from './types';
+import {RelationDefinitionBase} from './decorators/relation.decorator';
 
 /**
  * This module defines the key classes representing building blocks for Domain
@@ -45,6 +46,7 @@ export interface ModelDefinitionSyntax {
   name: string;
   properties?: {[name: string]: PropertyDefinition | PropertyType};
   settings?: {[name: string]: any};
+  relations?: {[name: string]: RelationDefinitionBase};
   [attribute: string]: any;
 }
 
@@ -55,14 +57,15 @@ export class ModelDefinition {
   readonly name: string;
   properties: {[name: string]: PropertyDefinition};
   settings: {[name: string]: any};
+  relations: {[name: string]: RelationDefinitionBase};
   // indexes: Map<string, any>;
   [attribute: string]: any; // Other attributes
 
   constructor(nameOrDef: string | ModelDefinitionSyntax) {
     if (typeof nameOrDef === 'string') {
       nameOrDef = {name: nameOrDef};
     }
-    const {name, properties, settings} = nameOrDef;
+    const {name, properties, settings, relations} = nameOrDef;
 
     this.name = name;
 
@@ -74,6 +77,7 @@ export class ModelDefinition {
     }
 
     this.settings = settings || new Map();
+    this.relations = relations || {};
   }
 
   /**

packages/repository/src/repositories/legacy-juggler-bridge.ts

@@ -18,6 +18,11 @@ import {
 import {Entity, ModelDefinition} from '../model';
 import {Filter, Where} from '../query';
 import {EntityCrudRepository} from './repository';
+import {createHasManyRepositoryFactory} from './relation.factory';
+import {HasManyDefinition} from '../decorators/relation.decorator';
+// need the import for exporting of a return type
+// tslint:disable-next-line:no-unused-variable
+import {HasManyRepository} from './relation.repository';
 
 export namespace juggler {
   export import DataSource = legacy.DataSource;
@@ -117,6 +122,43 @@ export class DefaultCrudRepository<T extends Entity, ID>
     this.modelClass.attachTo(dataSource);
   }
 
+  /**
+   * Function to create a constrained relation repository factory
+   *
+   * ```ts
+   * class CustomerRepository extends DefaultCrudRepository<
+   *   Customer,
+   *   typeof Customer.prototype.id
+   * > {
+   *   public orders: HasManyRepositoryFactory<Order, typeof Order.prototype.id>;
+   *
+   *   constructor(
+   *     protected db: juggler.DataSource,
+   *     orderRepository: EntityCrudRepository<Order, typeof Order.prototype.id>,
+   *   ) {
+   *     super(Customer, db);
+   *     this.orders = this._createHasManyRepositoryFactoryFor(
+   *       'orders',
+   *       orderRepository,
+   *     );
+   *   }
+   * }
+   * ```
+   *
+   * @param relationName Name of the relation defined on the source model
+   * @param targetRepo Target repository instance
+   */
+  protected _createHasManyRepositoryFactoryFor<Target extends Entity>(
+    relationName: string,
+    targetRepo: EntityCrudRepository<Target, typeof Entity.prototype.id>,
+  ) {
+    const meta = this.entityClass.definition.relations[relationName];
+    return createHasManyRepositoryFactory(
+      meta as HasManyDefinition,
+      targetRepo,
+    );
+  }
+
   async create(entity: Partial<T>, options?: Options): Promise<T> {
     const model = await ensurePromise(this.modelClass.create(entity, options));
     return this.toEntity(model);

packages/repository/src/repositories/relation.factory.ts

@@ -4,49 +4,45 @@
 // License text available at https://opensource.org/licenses/MIT
 
 import {EntityCrudRepository} from './repository';
-import {RelationType} from '../decorators/relation.decorator';
+import {HasManyDefinition} from '../decorators/relation.decorator';
 import {Entity} from '../model';
 import {
-  HasManyEntityCrudRepository,
+  HasManyRepository,
   DefaultHasManyEntityCrudRepository,
 } from './relation.repository';
 
-export interface RelationDefinitionBase {
-  type: RelationType;
-  keyTo: string;
-}
+export type HasManyRepositoryFactory<T extends Entity, ID> = (
+  fkValue: ID,
+) => HasManyRepository<T>;
 
-export interface HasManyDefinition extends RelationDefinitionBase {
-  type: RelationType.hasMany;
-}
 /**
  * Enforces a constraint on a repository based on a relationship contract
- * between models. Returns a relational repository that exposes applicable CRUD
- * method APIs for the related target repository. For example, if a Customer model is
- * related to an Order model via a HasMany relation, then, the relational
- * repository returned by this method would be constrained by a Customer model
- * instance's id(s).
+ * between models. For example, if a Customer model is related to an Order model
+ * via a HasMany relation, then, the relational repository returned by the
+ * factory function would be constrained by a Customer model instance's id(s).
  *
- * @param constraint The constraint to apply to the target repository. For
- * example, {id: '5'}.
- * @param relationMetadata The relation metadata used to used to describe the
+ * @param relationMeta The relation metadata used to describe the
  * relationship and determine how to apply the constraint.
- * @param targetRepository The repository which represents the target model of a
+ * @param targetRepo The repository which represents the target model of a
  * relation attached to a datasource.
- *
+ * @returns The factory function which accepts a foreign key value to constrain
+ * the given target repository
  */
-export function hasManyRepositoryFactory<SourceID, T extends Entity, ID>(
-  sourceModelId: SourceID,
-  relationMetadata: HasManyDefinition,
-  targetRepository: EntityCrudRepository<T, ID>,
-): HasManyEntityCrudRepository<T> {
-  switch (relationMetadata.type) {
-    case RelationType.hasMany:
-      const fkConstraint = {[relationMetadata.keyTo]: sourceModelId};
-
-      return new DefaultHasManyEntityCrudRepository<
-        T,
-        EntityCrudRepository<T, ID>
-      >(targetRepository, fkConstraint);
-  }
+export function createHasManyRepositoryFactory<T extends Entity, ID>(
+  relationMeta: HasManyDefinition,
+  targetRepo: EntityCrudRepository<T, ID>,
+): HasManyRepositoryFactory<T, ID> {
+  return function(fkValue: ID) {
+    const fkName = relationMeta.keyTo;
+    if (!fkName) {
+      throw new Error(
+        'The foreign key property name (keyTo) must be specified',
+      );
+    }
+    return new DefaultHasManyEntityCrudRepository<
+      T,
+      ID,
+      EntityCrudRepository<T, ID>
+    >(targetRepo, {[fkName]: fkValue});
+  };
 }

packages/repository/src/repositories/relation.repository.ts

@@ -16,7 +16,7 @@ import {Filter, Where} from '../query';
 /**
  * CRUD operations for a target repository of a HasMany relation
  */
-export interface HasManyEntityCrudRepository<T extends Entity> {
+export interface HasManyRepository<T extends Entity> {
   /**
    * Create a target model instance
    * @param targetModelData The target model data
@@ -54,8 +54,9 @@ export interface HasManyEntityCrudRepository<T extends Entity> {
 
 export class DefaultHasManyEntityCrudRepository<
   T extends Entity,
-  TargetRepository extends EntityCrudRepository<T, typeof Entity.prototype.id>
-> implements HasManyEntityCrudRepository<T> {
+  ID,
+  TargetRepository extends EntityCrudRepository<T, ID>
+> implements HasManyRepository<T> {
   /**
    * Constructor of DefaultHasManyEntityCrudRepository
    * @param targetRepository the related target model repository instance