@loopback/repository 1.15.4 → 1.18.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';
@@ -110,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 */
@@ -258,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 {
@@ -464,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-through.repository.ts

@@ -0,0 +1,100 @@
+// 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 {Count, DataObject, Entity, Filter, 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<Target>;
+
+  /**
+   * 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>;
+}

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';

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/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>;

package/src/relations/relation.types.ts

@@ -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

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 ?? ''};
     });
   }
 }