@loopback/repository 1.15.3 → 1.17.0

package/src/define-model-class.ts

@@ -0,0 +1,88 @@
+// Copyright IBM Corp. 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 * as assert from 'assert';
+import {DataObject, PrototypeOf} from './common-types';
+import {Model, ModelDefinition} from './model';
+
+/**
+ * Create (define) a new model class with the given name and definition.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const Product = defineModelClass(Entity, new ModelDefinition('Product'));
+ * ```
+ *
+ * To enable type safety, you should describe properties of your model:
+ *
+ * ```ts
+ * const Product = defineModelClass<
+ *  typeof Entity,
+ *  {id: number, name: string}
+ * >(Entity, new ModelDefinition('Product'));
+ * ```
+ *
+ * If your model allows arbitrary (free-form) properties, then add `AnyObject`
+ * to the type describing model properties.
+ *
+ * ```ts
+ * const Product = defineModelClass<
+ *  typeof Entity,
+ *  AnyObject & {id: number},
+ * >(Entity, new ModelDefinition('Product'));
+ * ```
+ *
+ * @param base The base model to extend, typically Model or Entity.
+ *  You can also use your own base class, e.g. `User`.
+ * @param definition Definition of the model to create.
+ * @template BaseCtor Constructor type of the base class,
+ *   e.g `typeof Model` or `typeof Entity`
+ * @template Props Interface describing model properties,
+ *   e.g. `{title: string}` or `AnyObject & {id: number}`.
+ */
+export function defineModelClass<
+  BaseCtor extends typeof Model,
+  Props extends object = {}
+>(
+  base: BaseCtor /* Model or Entity */,
+  definition: ModelDefinition,
+): DynamicModelCtor<BaseCtor, Props> {
+  const modelName = definition.name;
+  const defineNamedModelClass = new Function(
+    base.name,
+    `return class ${modelName} extends ${base.name} {}`,
+  );
+  const modelClass = defineNamedModelClass(base) as DynamicModelCtor<
+    BaseCtor,
+    Props
+  >;
+  assert.equal(modelClass.name, modelName);
+  modelClass.definition = definition;
+  return modelClass;
+}
+
+/**
+ * A type describing a model class created via `defineModelClass`.
+ *
+ * Assuming template arguments `BaseCtor` and `Props`, this type describes
+ * a class constructor with the following properties:
+ * - a constructor function accepting `DataObject<Props>` as the only argument,
+ *   this argument is optional
+ * - all static fields (properties, methods) from `BaseCtor` are inherited and
+ *   available as static fields on the dynamic class
+ * - all prototype fields from `BaseCtor` prototype are inherited and available
+ *   as prototype fields on the dynamic class
+ */
+export type DynamicModelCtor<
+  BaseCtor extends typeof Model,
+  Props extends object
+> = BaseCtor & {
+  /** Model constructor accepting partial model data. */
+  new (data?: DataObject<PrototypeOf<BaseCtor> & Props>): PrototypeOf<
+    BaseCtor
+  > &
+    Props;
+};

package/src/errors/invalid-relation.error.ts

@@ -18,7 +18,7 @@ export class InvalidRelationError<Props extends object = {}> extends Error {
     extraProperties?: Props,
   ) {
     const {name, type, source} = relationMeta;
-    const model = (source && source.modelName) || '<Unknown Model>';
+    const model = source?.modelName || '<Unknown Model>';
     const message = `Invalid ${type} definition for ${model}#${name}: ${reason}`;
     super(message);
 

package/src/index.ts

@@ -7,6 +7,7 @@ export * from './common-types';
 export * from './connectors';
 export * from './datasource';
 export * from './decorators';
+export * from './define-model-class';
 export * from './errors';
 export * from './mixins';
 export * from './model';

package/src/mixins/repository.mixin.ts

@@ -5,7 +5,7 @@
 
 import {Binding, BindingScope, createBindingFromClass} from '@loopback/context';
 import {Application} from '@loopback/core';
-import * as debugFactory from 'debug';
+import debugFactory from 'debug';
 import {Class} from '../common-types';
 import {SchemaMigrationOptions} from '../datasource';
 import {juggler, Repository} from '../repositories';
@@ -29,12 +29,6 @@ const debug = debugFactory('loopback:repository:mixin');
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function RepositoryMixin<T extends Class<any>>(superClass: T) {
   return class extends superClass {
-    // A mixin class has to take in a type any[] argument!
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    constructor(...args: any[]) {
-      super(...args);
-    }
-
     /**
      * Add a repository to this application.
      *
@@ -116,13 +110,17 @@ export function RepositoryMixin<T extends Class<any>>(superClass: T) {
     ): Binding<D> {
       // We have an instance of
       if (dataSource instanceof juggler.DataSource) {
-        const key = `datasources.${name || dataSource.name}`;
+        // 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');
       } else if (typeof dataSource === 'function') {
+        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+        name = name || dataSource.dataSourceName;
         const binding = createBindingFromClass(dataSource, {
-          name: name || dataSource.dataSourceName,
+          name,
           namespace: 'datasources',
           type: 'datasource',
           defaultScope: BindingScope.SINGLETON,

package/src/model.ts

@@ -90,8 +90,8 @@ export class ModelDefinition {
       }
     }
 
-    this.settings = settings || new Map();
-    this.relations = relations || {};
+    this.settings = settings ?? new Map();
+    this.relations = relations ?? {};
   }
 
   /**

package/src/query.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as assert from 'assert';
+import assert from 'assert';
 import {AnyObject} from './common-types';
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -170,8 +170,18 @@ export type Fields<MT = AnyObject> = {[P in keyof MT]?: boolean};
  * `{relation: 'aRelationName', scope: {<AFilterObject>}}`
  */
 export interface Inclusion<MT extends object = AnyObject> {
+  // ^^^ TODO(semver-major): remove the generic argument <MT>
+
   relation: string;
-  scope?: Filter<MT>;
+
+  // Technically, we should restrict the filter to target model.
+  // That is unfortunately rather difficult to achieve, because
+  // an Entity does not provide type information about related models.
+  // We could use {ModelName}WithRelations interface for first-level inclusion,
+  // but that won't handle second-level (and deeper) inclusions.
+  // To keep things simple, we allow any filter here, effectively turning off
+  // compiler checks.
+  scope?: Filter<AnyObject>;
 }
 
 /**
@@ -248,7 +258,7 @@ export class WhereBuilder<MT extends object = AnyObject> {
   where: Where<MT>;
 
   constructor(w?: Where<MT>) {
-    this.where = w || {};
+    this.where = w ?? {};
   }
 
   private add(w: Where<MT>): this {
@@ -454,7 +464,7 @@ export class FilterBuilder<MT extends object = AnyObject> {
   filter: Filter<MT>;
 
   constructor(f?: Filter<MT>) {
-    this.filter = f || {};
+    this.filter = f ?? {};
   }
 
   /**

package/src/relations/belongs-to/belongs-to-accessor.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as debugFactory from 'debug';
+import debugFactory from 'debug';
 import {DataObject} from '../../common-types';
 import {Entity} from '../../model';
 import {EntityCrudRepository} from '../../repositories/repository';
@@ -13,8 +13,8 @@ import {
   InclusionResolver,
 } from '../relation.types';
 import {resolveBelongsToMetadata} from './belongs-to.helpers';
-import {DefaultBelongsToRepository} from './belongs-to.repository';
 import {createBelongsToInclusionResolver} from './belongs-to.inclusion-resolver';
+import {DefaultBelongsToRepository} from './belongs-to.repository';
 
 const debug = debugFactory('loopback:repository:belongs-to-accessor');
 
@@ -53,6 +53,12 @@ export function createBelongsToAccessor<
     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/strongloop/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 DefaultBelongsToRepository(

package/src/relations/belongs-to/belongs-to.helpers.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as debugFactory from 'debug';
+import debugFactory from 'debug';
 import {InvalidRelationError} from '../../errors';
 import {isTypeResolver} from '../../type-resolver';
 import {BelongsToDefinition, RelationType} from '../relation.types';

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

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as debugFactory from 'debug';
+import debugFactory from 'debug';
 import {DataObject} from '../../common-types';
 import {Entity} from '../../model';
 import {EntityCrudRepository} from '../../repositories/repository';

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

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as debugFactory from 'debug';
+import debugFactory from 'debug';
 import {camelCase} from 'lodash';
 import {InvalidRelationError} from '../../errors';
 import {isTypeResolver} from '../../type-resolver';
@@ -50,8 +50,16 @@ export function resolveHasManyMetadata(
     throw new InvalidRelationError(reason, relationMeta);
   }
 
-  const keyFrom = sourceModel.getIdProperties()[0];
-
+  // 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]) {
@@ -72,5 +80,8 @@ export function resolveHasManyMetadata(
     throw new InvalidRelationError(reason, relationMeta);
   }
 
-  return Object.assign(relationMeta, {keyFrom, keyTo: defaultFkName});
+  return Object.assign(relationMeta, {
+    keyFrom,
+    keyTo: defaultFkName,
+  } as HasManyResolvedDefinition);
 }

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

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as debugFactory from 'debug';
+import debugFactory from 'debug';
 import {AnyObject, Options} from '../../common-types';
 import {Entity} from '../../model';
 import {Filter, Inclusion} from '../../query';
@@ -42,7 +42,7 @@ export function createHasManyInclusionResolver<
 
   return async function fetchHasManyModels(
     entities: Entity[],
-    inclusion: Inclusion<Entity>,
+    inclusion: Inclusion<AnyObject>,
     options?: Options,
   ): Promise<((Target & TargetRelations)[] | undefined)[]> {
     if (!entities.length) return [];
@@ -55,7 +55,10 @@ export function createHasManyInclusionResolver<
     const targetKey = relationMeta.keyTo as StringKeyOf<Target>;
 
     debug('Parameters:', {sourceKey, sourceIds, targetKey});
-    debug('sourceId types', sourceIds.map(i => typeof i));
+    debug(
+      'sourceId types',
+      sourceIds.map(i => typeof i),
+    );
 
     const targetRepo = await getTargetRepo();
     const targetsFound = await findByForeignKeys(

package/src/relations/has-one/has-one-repository.factory.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as debugFactory from 'debug';
+import debugFactory from 'debug';
 import {DataObject} from '../../common-types';
 import {Entity} from '../../model';
 import {EntityCrudRepository} from '../../repositories/repository';

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

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as debugFactory from 'debug';
+import debugFactory from 'debug';
 import {camelCase} from 'lodash';
 import {InvalidRelationError} from '../../errors';
 import {isTypeResolver} from '../../type-resolver';
@@ -50,7 +50,16 @@ export function resolveHasOneMetadata(
     throw new InvalidRelationError(reason, relationMeta);
   }
 
-  const keyFrom = sourceModel.getIdProperties()[0];
+  // 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

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

@@ -39,7 +39,7 @@ export function createHasOneInclusionResolver<
 
   return async function fetchHasOneModel(
     entities: Entity[],
-    inclusion: Inclusion<Entity>,
+    inclusion: Inclusion<AnyObject>,
     options?: Options,
   ): Promise<((Target & TargetRelations) | undefined)[]> {
     if (!entities.length) return [];

package/src/relations/relation.decorator.ts

@@ -33,7 +33,7 @@ export function getModelRelations(
 ): RelationDefinitionMap {
   // Build model definitions if `@model` is missing
   const modelDef = buildModelDefinition(modelCtor);
-  return (modelDef && modelDef.relations) || {};
+  return modelDef?.relations || {};
 }
 
 //

package/src/relations/relation.helpers.ts

@@ -3,9 +3,9 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as assert from 'assert';
-import * as debugFactory from 'debug';
-import * as _ from 'lodash';
+import assert from 'assert';
+import debugFactory from 'debug';
+import _ from 'lodash';
 import {
   AnyObject,
   Entity,
@@ -14,13 +14,14 @@ import {
   Inclusion,
   Options,
   Where,
+  FilterBuilder,
 } from '..';
 const debug = debugFactory('loopback:repository:relation-helpers');
 
 /**
  * Finds model instances that contain any of the provided foreign key values.
  *
- * @param targetRepository - The target repository where the model instances are found
+ * @param targetRepository - The target repository where the related model instances are found
  * @param fkName - Name of the foreign key
  * @param fkValues - One value or array of values of the foreign key to be included
  * @param scope - Additional scope constraints (not currently supported)
@@ -37,12 +38,6 @@ export async function findByForeignKeys<
   scope?: Filter<Target>,
   options?: Options,
 ): Promise<(Target & TargetRelations)[]> {
-  // throw error if scope is defined and non-empty
-  // see https://github.com/strongloop/loopback-next/issues/3453
-  if (scope && !_.isEmpty(scope)) {
-    throw new Error('scope is not supported');
-  }
-
   let value;
 
   if (Array.isArray(fkValues)) {
@@ -60,9 +55,15 @@ export async function findByForeignKeys<
   }
 
   const where = ({[fkName]: value} as unknown) as Where<Target>;
-  const targetFilter = {where};
 
-  return targetRepository.find(targetFilter, options);
+  if (scope && !_.isEmpty(scope)) {
+    // combine where clause to scope filter
+    scope = new FilterBuilder(scope).impose({where}).filter;
+  } else {
+    scope = {where} as Filter<Target>;
+  }
+
+  return targetRepository.find(scope, options);
 }
 
 export type StringKeyOf<T> = Extract<keyof T, string>;
@@ -186,7 +187,10 @@ export function flattenTargetsOfOneToManyRelation<Target extends Entity>(
 ): (Target[] | undefined)[] {
   debug('flattenTargetsOfOneToManyRelation');
   debug('sourceIds', sourceIds);
-  debug('sourceId types', sourceIds.map(i => typeof i));
+  debug(
+    'sourceId types',
+    sourceIds.map(i => typeof i),
+  );
   debug('targetEntities', targetEntities);
   debug('targetKey', targetKey);
 

package/src/relations/relation.types.ts

@@ -3,7 +3,7 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import {Options} from '../common-types';
+import {AnyObject, Options} from '../common-types';
 import {Entity} from '../model';
 import {Inclusion} from '../query';
 import {TypeResolver} from '../type-resolver';
@@ -59,13 +59,62 @@ export interface HasManyDefinition extends RelationDefinitionBase {
   targetsMany: true;
 
   /**
-   * The foreign key used by the target model.
+   * keyTo: The foreign key used by the target model for this relation.
+   * keyFrom: The source key used by the source model for this relation.
    *
    * E.g. when a Customer has many Order instances, then keyTo is "customerId".
    * Note that "customerId" is the default FK assumed by the framework, users
    * can provide a custom FK name by setting "keyTo".
+   * And Customer.id is keyFrom. keyFrom defaults to the id property of a model.
+   * Users can provide a custom source key name by setting "keyTo".
+   *
    */
   keyTo?: string;
+  keyFrom?: string;
+}
+
+/**
+ * A `hasManyThrough` relation defines a many-to-many connection with another model.
+ * This relation indicates that the declaring model can be matched with zero or more
+ * instances of another model by proceeding through a third model.
+ *
+ * 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 interface HasManyThroughDefinition extends RelationDefinitionBase {
+  type: RelationType.hasMany;
+  targetsMany: true;
+
+  /**
+   * The foreign key in the source model, e.g. Customer#id.
+   */
+  keyFrom: string;
+
+  /**
+   * The primary key of the target model, e.g Seller#id.
+   */
+  keyTo: string;
+
+  through: {
+    /**
+     * The through model of this relation.
+     *
+     * E.g. when a Customer has many Order instances and a Seller has many Order instances,
+     * then Order is through.
+     */
+    model: TypeResolver<Entity, typeof Entity>;
+
+    /**
+     * The foreign key of the source model defined in the through model, e.g. Order#customerId
+     */
+    keyFrom: string;
+
+    /**
+     * The foreign key of the target model defined in the through model, e.g. Order#sellerId
+     */
+    keyTo: string;
+  };
 }
 
 export interface BelongsToDefinition extends RelationDefinitionBase {
@@ -88,13 +137,17 @@ export interface HasOneDefinition extends RelationDefinitionBase {
   targetsMany: false;
 
   /**
-   * The foreign key used by the target model.
+   * keyTo: The foreign key used by the target model for this relation.
+   * keyFrom: The source key used by the source model for this relation.
    *
    * E.g. when a Customer has one Address instance, then keyTo is "customerId".
    * Note that "customerId" is the default FK assumed by the framework, users
    * can provide a custom FK name by setting "keyTo".
+   * And Customer.id is keyFrom. keyFrom defaults to the id property of a model.
+   * Users can provide a custom source key name by setting "keyTo".
    */
   keyTo?: string;
+  keyFrom?: string;
 }
 
 /**
@@ -102,6 +155,7 @@ export interface HasOneDefinition extends RelationDefinitionBase {
  */
 export type RelationMetadata =
   | HasManyDefinition
+  | HasManyThroughDefinition
   | BelongsToDefinition
   | HasOneDefinition
   // TODO(bajtos) add other relation types and remove RelationDefinitionBase once
@@ -126,7 +180,7 @@ export type InclusionResolver<S extends Entity, T extends Entity> = (
   /**
    * Inclusion requested by the user (e.g. scope constraints to apply).
    */
-  inclusion: Inclusion,
+  inclusion: Inclusion<AnyObject>,
   /**
    * Generic options object, e.g. carrying the Transaction object.
    */

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

@@ -3,14 +3,11 @@
 // This file is licensed under the MIT License.
 // License text available at https://opensource.org/licenses/MIT
 
-import * as legacy from 'loopback-datasource-juggler';
-
-import {Options, DataObject} from '../common-types';
+import legacy from 'loopback-datasource-juggler';
+import {DataObject, Options} from '../common-types';
 import {Entity} from '../model';
-
-import {KeyValueRepository, KeyValueFilter} from './kv.repository';
-
-import {juggler, ensurePromise} from './legacy-juggler-bridge';
+import {KeyValueFilter, KeyValueRepository} from './kv.repository';
+import {ensurePromise, juggler} from './legacy-juggler-bridge';
 
 /**
  * Polyfill for Symbol.asyncIterator
@@ -103,7 +100,7 @@ class AsyncKeyIteratorImpl implements AsyncIterator<string> {
   next() {
     const key = ensurePromise<string | undefined>(this.keys.next());
     return key.then(k => {
-      return {done: k === undefined, value: k || ''};
+      return {done: k === undefined, value: k ?? ''};
     });
   }
 }