@loopback/repository 2.2.1 → 2.5.1

package/src/mixins/repository.mixin.ts

@@ -3,15 +3,60 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {Binding, BindingScope, createBindingFromClass} from '@loopback/context';
-import {Application} from '@loopback/core';
+import {
+  Binding,
+  BindingFromClassOptions,
+  BindingScope,
+  createBindingFromClass,
+} from '@loopback/context';
+import {
+  Application,
+  Component,
+  Constructor,
+  CoreBindings,
+  MixinTarget,
+} from '@loopback/core';
 import debugFactory from 'debug';
 import {Class} from '../common-types';
 import {SchemaMigrationOptions} from '../datasource';
+import {RepositoryBindings, RepositoryTags} from '../keys';
+import {Model} from '../model';
 import {juggler, Repository} from '../repositories';
 
 const debug = debugFactory('loopback:repository:mixin');
 
+// FIXME(rfeng): Workaround for https://github.com/microsoft/rushstack/pull/1867
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import {
+  BindingAddress,
+  BindingFilter,
+  JSONObject,
+  Provider,
+  Context,
+  ContextSubscriptionManager,
+  ContextEvent,
+  Interceptor,
+  InterceptorBindingOptions,
+  ResolutionOptions,
+  BindingKey,
+  ValueOrPromise,
+  ContextEventObserver,
+  ContextObserver,
+  Subscription,
+  BindingComparator,
+  ContextView,
+  ResolutionSession,
+  BindingCreationPolicy,
+  ContextInspectOptions,
+} from '@loopback/context';
+import {
+  Server,
+  ApplicationConfig,
+  ApplicationMetadata,
+  LifeCycleObserver,
+  ServiceOptions,
+} from '@loopback/core';
+
 /**
  * A mixin class for Application that creates a .repository()
  * function to register a repository automatically. Also overrides
@@ -26,13 +71,15 @@ const debug = debugFactory('loopback:repository:mixin');
  * called <a href="#RepositoryMixinDoc">RepositoryMixinDoc</a>
  *
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function RepositoryMixin<T extends Class<any>>(superClass: T) {
+export function RepositoryMixin<T extends MixinTarget<Application>>(
+  superClass: T,
+) {
   return class extends superClass {
     /**
      * Add a repository to this application.
      *
      * @param repoClass - The repository to add.
+     * @param nameOrOptions - Name or options for the binding
      *
      * @example
      * ```ts
@@ -60,14 +107,14 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     repository<R extends Repository<any>>(
       repoClass: Class<R>,
-      name?: string,
+      nameOrOptions?: string | BindingFromClassOptions,
     ): Binding<R> {
       const binding = createBindingFromClass(repoClass, {
-        name,
-        namespace: 'repositories',
-        type: 'repository',
+        namespace: RepositoryBindings.REPOSITORIES,
+        type: RepositoryTags.REPOSITORY,
         defaultScope: BindingScope.TRANSIENT,
-      });
+        ...toOptions(nameOrOptions),
+      }).tag(RepositoryTags.REPOSITORY);
       this.add(binding);
       return binding;
     }
@@ -86,7 +133,8 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
      * Add the dataSource to this application.
      *
      * @param dataSource - The dataSource to add.
-     * @param name - The binding name of the datasource; defaults to dataSource.name
+     * @param nameOrOptions - The binding name or options of the datasource;
+     * defaults to dataSource.name
      *
      * @example
      * ```ts
@@ -106,22 +154,24 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
      */
     dataSource<D extends juggler.DataSource>(
       dataSource: Class<D> | D,
-      name?: string,
+      nameOrOptions?: string | BindingFromClassOptions,
     ): Binding<D> {
+      const options = toOptions(nameOrOptions);
       // We have an instance of
       if (dataSource instanceof juggler.DataSource) {
         // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-        name = name || dataSource.name;
-        const key = `datasources.${name}`;
-        return this.bind(key).to(dataSource).tag('datasource');
+        const name = options.name || dataSource.name;
+        const namespace = options.namespace ?? RepositoryBindings.DATASOURCES;
+        const key = `${namespace}.${name}`;
+        return this.bind(key).to(dataSource).tag(RepositoryTags.DATASOURCE);
       } else if (typeof dataSource === 'function') {
         // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-        name = name || dataSource.dataSourceName;
+        options.name = options.name || dataSource.dataSourceName;
         const binding = createBindingFromClass(dataSource, {
-          name,
-          namespace: 'datasources',
-          type: 'datasource',
+          namespace: RepositoryBindings.DATASOURCES,
+          type: RepositoryTags.DATASOURCE,
           defaultScope: BindingScope.SINGLETON,
+          ...options,
         });
         this.add(binding);
         return binding;
@@ -130,11 +180,22 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
       }
     }
 
+    /**
+     * Register a model class as a binding in the target context
+     * @param modelClass - Model class
+     */
+    model<M extends Class<unknown>>(modelClass: M) {
+      const binding = createModelClassBinding(modelClass);
+      this.add(binding);
+      return binding;
+    }
+
     /**
      * Add a component to this application. Also mounts
      * all the components repositories.
      *
      * @param component - The component to add.
+     * @param nameOrOptions - Name or options for the binding.
      *
      * @example
      * ```ts
@@ -151,9 +212,17 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
      * app.component(ProductComponent);
      * ```
      */
-    public component(component: Class<unknown>, name?: string) {
-      super.component(component, name);
-      this.mountComponentRepositories(component);
+    // Unfortunately, TypeScript does not allow overriding methods inherited
+    // from mapped types. https://github.com/microsoft/TypeScript/issues/38496
+    // eslint-disable-next-line @typescript-eslint/ban-ts-ignore
+    // @ts-ignore
+    public component<C extends Component = Component>(
+      componentCtor: Constructor<C>,
+      nameOrOptions?: string | BindingFromClassOptions,
+    ) {
+      const binding = super.component(componentCtor, nameOrOptions);
+      this.mountComponentRepositories(componentCtor);
+      return binding;
     }
 
     /**
@@ -164,8 +233,10 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
      * @param component - The component to mount repositories of
      */
     mountComponentRepositories(component: Class<unknown>) {
-      const componentKey = `components.${component.name}`;
-      const compInstance = this.getSync(componentKey);
+      const componentKey = `${CoreBindings.COMPONENTS}.${component.name}`;
+      const compInstance = this.getSync<{
+        repositories?: Class<Repository<Model>>[];
+      }>(componentKey);
 
       if (compInstance.repositories) {
         for (const repo of compInstance.repositories) {
@@ -200,10 +271,10 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
 
       // Look up all datasources and update/migrate schemas one by one
       const dsBindings: Readonly<Binding<object>>[] = this.findByTag(
-        'datasource',
+        RepositoryTags.DATASOURCE,
       );
       for (const b of dsBindings) {
-        const ds = await this.get(b.key);
+        const ds = await this.get<juggler.DataSource>(b.key);
 
         if (operation in ds && typeof ds[operation] === 'function') {
           debug('Migrating dataSource %s', b.key);
@@ -216,6 +287,17 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
   };
 }
 
+/**
+ * Normalize name or options to `BindingFromClassOptions`
+ * @param nameOrOptions - Name or options for binding from class
+ */
+function toOptions(nameOrOptions?: string | BindingFromClassOptions) {
+  if (typeof nameOrOptions === 'string') {
+    return {name: nameOrOptions};
+  }
+  return nameOrOptions ?? {};
+}
+
 /**
  * Interface for an Application mixed in with RepositoryMixin
  */
@@ -231,6 +313,7 @@ export interface ApplicationWithRepositories extends Application {
     dataSource: Class<D> | D,
     name?: string,
   ): Binding<D>;
+  model<M extends Class<unknown>>(modelClass: M): Binding<M>;
   component(component: Class<unknown>, name?: string): Binding;
   mountComponentRepositories(component: Class<unknown>): void;
   migrateSchema(options?: SchemaMigrationOptions): Promise<void>;
@@ -372,3 +455,15 @@ export class RepositoryMixinDoc {
    */
   async migrateSchema(options?: SchemaMigrationOptions): Promise<void> {}
 }
+
+/**
+ * Create a binding for the given model class
+ * @param modelClass - Model class
+ */
+export function createModelClassBinding<M extends Class<unknown>>(
+  modelClass: M,
+) {
+  return Binding.bind<M>(`${RepositoryBindings.MODELS}.${modelClass.name}`)
+    .to(modelClass)
+    .tag(RepositoryTags.MODEL);
+}

package/src/model.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {AnyObject, DataObject, Options} from './common-types';
+import {AnyObject, DataObject, Options, PrototypeOf} from './common-types';
 import {JsonSchema} from './index';
 import {RelationMetadata} from './relations';
 import {TypeResolver} from './type-resolver';
@@ -189,14 +189,22 @@ function asJSON(value: any): any {
   return value;
 }
 
+/**
+ * Convert a value to a plain object as DTO.
+ *
+ * - The prototype of the value in primitive types are preserved,
+ *   like `Date`, `ObjectId`.
+ * - If the value is an instance of custom model, call `toObject` to convert.
+ * - If the value is an array, convert each element recursively.
+ *
+ * @param value the value to convert
+ * @param options the options
+ */
 function asObject(value: any, options?: Options): any {
   if (value == null) return value;
   if (typeof value.toObject === 'function') {
     return value.toObject(options);
   }
-  if (typeof value.toJSON === 'function') {
-    return value.toJSON();
-  }
   if (Array.isArray(value)) {
     return value.map(item => asObject(item, options));
   }
@@ -217,7 +225,7 @@ export abstract class Model {
    * Serialize into a plain JSON object
    */
   toJSON(): Object {
-    const def = (<typeof Model>this.constructor).definition;
+    const def = (this.constructor as typeof Model).definition;
     if (def == null || def.settings.strict === false) {
       return this.toObject({ignoreUnknownProperties: false});
     }
@@ -249,18 +257,39 @@ export abstract class Model {
 
   /**
    * Convert to a plain object as DTO
+   *
+   * If `ignoreUnknownProperty` is set to false, convert all properties in the
+   * model instance, otherwise only convert the ones defined in the model
+   * definitions.
+   *
+   * See function `asObject` for each property's conversion rules.
    */
   toObject(options?: Options): Object {
-    let obj: AnyObject;
+    const def = (this.constructor as typeof Model).definition;
+    const obj: AnyObject = {};
+
     if (options && options.ignoreUnknownProperties === false) {
-      obj = {};
+      const hiddenProperties: string[] = def?.settings.hiddenProperties || [];
       for (const p in this) {
-        const val = (this as AnyObject)[p];
-        obj[p] = asObject(val, options);
+        if (!hiddenProperties.includes(p)) {
+          const val = (this as AnyObject)[p];
+          obj[p] = asObject(val, options);
+        }
       }
-    } else {
-      obj = this.toJSON();
+      return obj;
     }
+
+    const props = def.properties;
+    const keys = Object.keys(props);
+
+    for (const i in keys) {
+      const propertyName = keys[i];
+      const val = (this as AnyObject)[propertyName];
+
+      if (val === undefined) continue;
+      obj[propertyName] = asObject(val, options);
+    }
+
     return obj;
   }
 
@@ -367,3 +396,37 @@ export class Event {
 export type EntityData = DataObject<Entity>;
 
 export type EntityResolver<T extends Entity> = TypeResolver<T, typeof Entity>;
+
+/**
+ * Check model data for navigational properties linking to related models.
+ * Throw a descriptive error if any such property is found.
+ *
+ * @param modelClass Model constructor, e.g. `Product`.
+ * @param entityData  Model instance or a plain-data object,
+ * e.g. `{name: 'pen'}`.
+ */
+export function rejectNavigationalPropertiesInData<M extends typeof Entity>(
+  modelClass: M,
+  data: DataObject<PrototypeOf<M>>,
+) {
+  const def = modelClass.definition;
+  const props = def.properties;
+
+  for (const r in def.relations) {
+    const relName = def.relations[r].name;
+    if (!(relName in data)) continue;
+
+    let msg =
+      'Navigational properties are not allowed in model data ' +
+      `(model "${modelClass.modelName}" property "${relName}"), ` +
+      'please remove it.';
+
+    if (relName in props) {
+      msg +=
+        ' The error might be invoked by belongsTo relations, please make' +
+        ' sure the relation name is not the same as the property name.';
+    }
+
+    throw new Error(msg);
+  }
+}

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

@@ -0,0 +1,193 @@
+import debugFactory from 'debug';
+import {camelCase} from 'lodash';
+import {
+  DataObject,
+  Entity,
+  HasManyDefinition,
+  InvalidRelationError,
+  isTypeResolver,
+} from '../..';
+import {resolveHasManyMetaHelper} from './has-many.helpers';
+
+const debug = debugFactory('loopback:repository:has-many-through-helpers');
+
+export type HasManyThroughResolvedDefinition = HasManyDefinition & {
+  keyTo: string;
+  keyFrom: string;
+  through: {
+    keyTo: string;
+    keyFrom: string;
+  };
+};
+
+/**
+ * Creates constraint used to query target
+ * @param relationMeta - hasManyThrough metadata to resolve
+ * @param throughInstances - Instances of through entities used to constrain the target
+ * @internal
+ *
+ * @example
+ * ```ts
+ * const resolvedMetadata = {
+ *  // .. other props
+ *  keyFrom: 'id',
+ *  keyTo: 'id',
+ *  through: {
+ *    model: () => CategoryProductLink,
+ *    keyFrom: 'categoryId',
+ *    keyTo: 'productId',
+ *  },
+ * };
+
+ * createTargetConstraint(resolvedMetadata, [
+      {
+        id: 2,
+        categoryId: 2,
+        productId: 8,
+      }, {
+        id: 2,
+        categoryId: 2,
+        productId: 9,
+      }
+  ]);
+ * ```
+ */
+export function createTargetConstraint<
+  Target extends Entity,
+  Through extends Entity
+>(
+  relationMeta: HasManyThroughResolvedDefinition,
+  throughInstances: Through[],
+): DataObject<Target> {
+  const targetPrimaryKey = relationMeta.keyTo;
+  const targetFkName = relationMeta.through.keyTo;
+  const fkValues = throughInstances.map(
+    (throughInstance: Through) =>
+      throughInstance[targetFkName as keyof Through],
+  );
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const constraint: any = {
+    [targetPrimaryKey]: fkValues.length === 1 ? fkValues[0] : {inq: fkValues},
+  };
+  return constraint;
+}
+
+/**
+ * Creates constraint used to query through model
+ *
+ * @param relationMeta - hasManyThrough metadata to resolve
+ * @param fkValue - Value of the foreign key of the source model used to constrain through
+ * @param targetInstance - Instance of target entity used to constrain through
+ * @internal
+ *
+ * @example
+ * ```ts
+ * const resolvedMetadata = {
+ *  // .. other props
+ *  keyFrom: 'id',
+ *  keyTo: 'id',
+ *  through: {
+ *    model: () => CategoryProductLink,
+ *    keyFrom: 'categoryId',
+ *    keyTo: 'productId',
+ *  },
+ * };
+ * createThroughConstraint(resolvedMetadata, 1);
+ * ```
+ */
+export function createThroughConstraint<Through extends Entity, ForeignKeyType>(
+  relationMeta: HasManyThroughResolvedDefinition,
+  fkValue: ForeignKeyType,
+): DataObject<Through> {
+  const sourceFkName = relationMeta.through.keyFrom;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const constraint: any = {[sourceFkName]: fkValue};
+  return constraint;
+}
+
+/**
+ * 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 - hasManyThrough metadata to resolve
+ * @internal
+ */
+export function resolveHasManyThroughMetadata(
+  relationMeta: HasManyDefinition,
+): HasManyThroughResolvedDefinition {
+  // some checks and relationMeta.keyFrom are handled in here
+  relationMeta = resolveHasManyMetaHelper(relationMeta);
+
+  if (!relationMeta.through) {
+    const reason = 'through must be specified';
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+  if (!isTypeResolver(relationMeta.through?.model)) {
+    const reason = 'through.model must be a type resolver';
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  const throughModel = relationMeta.through.model();
+  const throughModelProperties = throughModel.definition?.properties;
+
+  const targetModel = relationMeta.target();
+  const targetModelProperties = targetModel.definition?.properties;
+
+  // check if metadata is already complete
+  if (
+    relationMeta.through.keyTo &&
+    throughModelProperties[relationMeta.through.keyTo] &&
+    relationMeta.through.keyFrom &&
+    throughModelProperties[relationMeta.through.keyFrom] &&
+    relationMeta.keyTo &&
+    targetModelProperties[relationMeta.keyTo]
+  ) {
+    // The explict cast is needed because of a limitation of type inference
+    return relationMeta as HasManyThroughResolvedDefinition;
+  }
+
+  const sourceModel = relationMeta.source;
+
+  debug(
+    'Resolved model %s from given metadata: %o',
+    targetModel.modelName,
+    targetModel,
+  );
+
+  debug(
+    'Resolved model %s from given metadata: %o',
+    throughModel.modelName,
+    throughModel,
+  );
+
+  const sourceFkName =
+    relationMeta.through.keyFrom ?? camelCase(sourceModel.modelName + '_id');
+  if (!throughModelProperties[sourceFkName]) {
+    const reason = `through model ${throughModel.name} is missing definition of source foreign key`;
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  const targetFkName =
+    relationMeta.through.keyTo ?? camelCase(targetModel.modelName + '_id');
+  if (!throughModelProperties[targetFkName]) {
+    const reason = `through model ${throughModel.name} is missing definition of target foreign key`;
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  const targetPrimaryKey =
+    relationMeta.keyTo ?? targetModel.definition.idProperties()[0];
+  if (!targetPrimaryKey || !targetModelProperties[targetPrimaryKey]) {
+    const reason = `target model ${targetModel.modelName} does not have any primary key (id property)`;
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  return Object.assign(relationMeta, {
+    keyTo: targetPrimaryKey,
+    keyFrom: relationMeta.keyFrom!,
+    through: {
+      ...relationMeta.through,
+      keyTo: targetFkName,
+      keyFrom: sourceFkName,
+    },
+  });
+}

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

@@ -30,41 +30,18 @@ export type HasManyResolvedDefinition = HasManyDefinition & {
 export function resolveHasManyMetadata(
   relationMeta: HasManyDefinition,
 ): HasManyResolvedDefinition {
-  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);
-  }
+  // some checks and relationMeta.keyFrom are handled in here
+  relationMeta = resolveHasManyMetaHelper(relationMeta);
 
   const targetModel = relationMeta.target();
   const targetModelProperties =
     targetModel.definition && targetModel.definition.properties;
 
   const sourceModel = relationMeta.source;
-  if (!sourceModel || !sourceModel.modelName) {
-    const reason = 'source model must be defined';
-    throw new InvalidRelationError(reason, relationMeta);
-  }
 
-  // keyFrom defaults to id property
-  let keyFrom;
-  if (
-    relationMeta.keyFrom &&
-    relationMeta.source.definition.properties[relationMeta.keyFrom]
-  ) {
-    keyFrom = relationMeta.keyFrom;
-  } else {
-    keyFrom = sourceModel.getIdProperties()[0];
-  }
-  // Make sure that if it already keys to the foreign key property,
-  // the key exists in the target model
   if (relationMeta.keyTo && targetModelProperties[relationMeta.keyTo]) {
     // The explicit cast is needed because of a limitation of type inference
-    return Object.assign(relationMeta, {keyFrom}) as HasManyResolvedDefinition;
+    return relationMeta as HasManyResolvedDefinition;
   }
 
   debug(
@@ -81,7 +58,44 @@ export function resolveHasManyMetadata(
   }
 
   return Object.assign(relationMeta, {
-    keyFrom,
     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;
+}