@loopback/repository 4.0.0-alpha.9 → 4.0.0

package/src/relations/relation.decorator.ts

@@ -0,0 +1,90 @@
+// Copyright IBM Corp. 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 {PropertyDecoratorFactory} from '@loopback/core';
+import {buildModelDefinition} from '../decorators';
+import {Model, RelationDefinitionMap} from '../model';
+import {RelationType} from './relation.types';
+
+export const RELATIONS_KEY = 'loopback:relations';
+
+/**
+ * Decorator for relations
+ * @param definition
+ * @returns A property decorator
+ */
+export function relation(definition?: Object) {
+  // Apply relation definition to the model class
+  return PropertyDecoratorFactory.createDecorator(RELATIONS_KEY, definition, {
+    decoratorName: '@relation',
+  });
+}
+
+/**
+ * Get metadata of all relations defined on a given model class.
+ *
+ * @param modelCtor - The model class (the constructor function).
+ * @returns A map of relation definitions
+ */
+export function getModelRelations(
+  modelCtor: typeof Model,
+): RelationDefinitionMap {
+  // Build model definitions if `@model` is missing
+  const modelDef = buildModelDefinition(modelCtor);
+  return modelDef?.relations || {};
+}
+
+//
+// placeholder decorators for relations that are not implemented yet
+// TODO: move these decorators to per-relation subdirectories
+//
+
+/**
+ * Decorator for embedsOne
+ * @param definition
+ * @returns A property decorator
+ */
+export function embedsOne(definition?: Object) {
+  const rel = Object.assign({type: RelationType.embedsOne}, definition);
+  return PropertyDecoratorFactory.createDecorator(RELATIONS_KEY, rel, {
+    decoratorName: '@embedsOne',
+  });
+}
+
+/**
+ * Decorator for embedsMany
+ * @param definition
+ * @returns A property decorator
+ */
+export function embedsMany(definition?: Object) {
+  const rel = Object.assign({type: RelationType.embedsMany}, definition);
+  return PropertyDecoratorFactory.createDecorator(RELATIONS_KEY, rel, {
+    decoratorName: '@embedsMany',
+  });
+}
+
+/**
+ * Decorator for referencesOne
+ * @param definition
+ * @returns A property decorator
+ */
+export function referencesOne(definition?: Object) {
+  const rel = Object.assign({type: RelationType.referencesOne}, definition);
+  return PropertyDecoratorFactory.createDecorator(RELATIONS_KEY, rel, {
+    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.helpers.ts

@@ -0,0 +1,364 @@
+// Copyright IBM Corp. 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 assert from 'assert';
+import debugFactory from 'debug';
+import _, {cloneDeep} from 'lodash';
+import {
+  AnyObject,
+  Entity,
+  EntityCrudRepository,
+  Filter,
+  FilterBuilder,
+  InclusionFilter,
+  Options,
+  Where,
+} 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 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
+ * @param options - Options for the operations
+ */
+export async function findByForeignKeys<
+  Target extends Entity,
+  TargetRelations extends object,
+  ForeignKey extends StringKeyOf<Target>,
+>(
+  targetRepository: EntityCrudRepository<Target, unknown, TargetRelations>,
+  fkName: ForeignKey,
+  fkValues: Target[ForeignKey][] | Target[ForeignKey],
+  scope?: Filter<Target> & {totalLimit?: number},
+  options?: Options,
+): Promise<(Target & TargetRelations)[]> {
+  let value;
+  scope = cloneDeep(scope);
+  if (Array.isArray(fkValues)) {
+    if (fkValues.length === 0) return [];
+    value = fkValues.length === 1 ? fkValues[0] : {inq: fkValues};
+  } else {
+    value = fkValues;
+  }
+  let useScopeFilterGlobally = false;
+  if (options) {
+    useScopeFilterGlobally = options.isThroughModelInclude;
+    //if its an include from a through model, fkValues will be an array
+    //however, in this case we DO want to use the scope in the entire query
+    //no in a per fk basis
+  }
+  //This code is to keep backward compatability. See https://github.com/loopbackio/loopback-next/issues/6832
+  //for more info
+  if (scope?.totalLimit) {
+    scope.limit = scope.totalLimit;
+    useScopeFilterGlobally = true;
+    delete scope.totalLimit;
+  }
+
+  const isScopeSet = scope && !_.isEmpty(scope);
+  if (isScopeSet && Array.isArray(fkValues) && !useScopeFilterGlobally) {
+    // since there is a scope, there could be a where filter, a limit, an order
+    // and we should run the scope in multiple queries so we can respect the
+    // scope filter params
+    const findPromises = fkValues.map(fk => {
+      const where = {[fkName]: fk} as unknown as Where<Target>;
+      let localScope = cloneDeep(scope);
+      // combine where clause to scope filter
+      localScope = new FilterBuilder(localScope).impose({where}).filter;
+      return targetRepository.find(localScope, options);
+    });
+    return Promise.all(findPromises).then(findResults => {
+      //findResults is an array of arrays for each scope result, so we need to flatten it before returning it
+      return _.flatten(findResults);
+    });
+  } else {
+    const where = {[fkName]: value} as unknown as Where<Target>;
+
+    if (isScopeSet) {
+      // 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>;
+
+/**
+ * Returns model instances that include related models that have a registered
+ * resolver.
+ *
+ * @param targetRepository - The target repository where the model instances are found
+ * @param entities - An array of entity instances or data
+ * @param include -Inclusion filter
+ * @param options - Options for the operations
+ */
+
+export async function includeRelatedModels<
+  T extends Entity,
+  Relations extends object = {},
+>(
+  targetRepository: EntityCrudRepository<T, unknown, Relations>,
+  entities: T[],
+  include?: InclusionFilter[],
+  options?: Options,
+): Promise<(T & Relations)[]> {
+  entities = cloneDeep(entities);
+  include = cloneDeep(include);
+  const result = entities as (T & Relations)[];
+  if (!include) return result;
+
+  const invalidInclusions = include.filter(
+    inclusionFilter => !isInclusionAllowed(targetRepository, inclusionFilter),
+  );
+  if (invalidInclusions.length) {
+    const msg =
+      'Invalid "filter.include" entries: ' +
+      invalidInclusions
+        .map(inclusionFilter => JSON.stringify(inclusionFilter))
+        .join('; ');
+    const err = new Error(msg);
+    Object.assign(err, {
+      code: 'INVALID_INCLUSION_FILTER',
+      statusCode: 400,
+    });
+    throw err;
+  }
+
+  const resolveTasks = include.map(async inclusionFilter => {
+    const relationName =
+      typeof inclusionFilter === 'string'
+        ? inclusionFilter
+        : inclusionFilter.relation;
+    const resolver = targetRepository.inclusionResolvers.get(relationName)!;
+    const targets = await resolver(entities, inclusionFilter, options);
+
+    result.forEach((entity, ix) => {
+      const src = entity as AnyObject;
+      src[relationName] = targets[ix];
+    });
+  });
+
+  await Promise.all(resolveTasks);
+
+  return result;
+}
+/**
+ * Checks if the resolver of the inclusion relation is registered
+ * in the inclusionResolver of the target repository
+ *
+ * @param targetRepository - The target repository where the relations are registered
+ * @param include - Inclusion filter
+ */
+function isInclusionAllowed<T extends Entity, Relations extends object = {}>(
+  targetRepository: EntityCrudRepository<T, unknown, Relations>,
+  include: InclusionFilter,
+): boolean {
+  const relationName = typeof include === 'string' ? include : include.relation;
+  if (!relationName) {
+    debug('isInclusionAllowed for %j? No: missing relation name', include);
+    return false;
+  }
+  const allowed = targetRepository.inclusionResolvers.has(relationName);
+  debug('isInclusionAllowed for %j (relation %s)? %s', include, allowed);
+  return allowed;
+}
+
+/**
+ * Returns an array of instances. The order of arrays is based on
+ * the order of sourceIds
+ *
+ * @param sourceIds - One value or array of values of the target key
+ * @param targetEntities - target entities that satisfy targetKey's value (ids).
+ * @param targetKey - name of the target key
+ *
+ */
+export function flattenTargetsOfOneToOneRelation<Target extends Entity>(
+  sourceIds: unknown[],
+  targetEntities: Target[],
+  targetKey: StringKeyOf<Target>,
+): (Target | undefined)[] {
+  const lookup = buildLookupMap<unknown, Target, Target>(
+    targetEntities,
+    targetKey,
+    reduceAsSingleItem,
+  );
+
+  return flattenMapByKeys(sourceIds, lookup);
+}
+
+/**
+ * Returns an array of instances. The order of arrays is based on
+ * as a result of one to many relation. The order of arrays is based on
+ * the order of sourceIds
+ *
+ * @param sourceIds - One value or array of values of the target key
+ * @param targetEntities - target entities that satisfy targetKey's value (ids).
+ * @param targetKey - name of the target key
+ *
+ */
+export function flattenTargetsOfOneToManyRelation<Target extends Entity>(
+  sourceIds: unknown[],
+  targetEntities: Target[],
+  targetKey: StringKeyOf<Target>,
+): (Target[] | undefined)[] {
+  debug('flattenTargetsOfOneToManyRelation');
+  debug('sourceIds', sourceIds);
+  debug(
+    'sourceId types',
+    sourceIds.map(i => typeof i),
+  );
+  debug('targetEntities', targetEntities);
+  debug('targetKey', targetKey);
+
+  const lookup = buildLookupMap<unknown, Target, Target[]>(
+    targetEntities,
+    targetKey,
+    reduceAsArray,
+  );
+
+  debug('lookup map', lookup);
+
+  return flattenMapByKeys(sourceIds, lookup);
+}
+
+/**
+ * Returns an array of instances from the target map. The order of arrays is based on
+ * the order of sourceIds
+ *
+ * @param sourceIds - One value or array of values (of the target key)
+ * @param targetMap - a map that matches sourceIds with instances
+ */
+export function flattenMapByKeys<T>(
+  sourceIds: unknown[],
+  targetMap: Map<unknown, T>,
+): (T | undefined)[] {
+  const result: (T | undefined)[] = new Array(sourceIds.length);
+  // mongodb: use string as key of targetMap, and convert sourceId to strings
+  // to make sure it gets the related instances.
+  sourceIds.forEach((id, index) => {
+    const key = normalizeKey(id);
+    const target = targetMap.get(key);
+    result[index] = target;
+  });
+
+  return result;
+}
+
+/**
+ * Returns a map which maps key values(ids) to instances. The instances can be
+ * grouped by different strategies.
+ *
+ * @param list - an array of instances
+ * @param keyName - key name of the source
+ * @param reducer - a strategy to reduce inputs to single item or array
+ */
+export function buildLookupMap<Key, InType, OutType = InType>(
+  list: InType[],
+  keyName: StringKeyOf<InType>,
+  reducer: (accumulator: OutType | undefined, current: InType) => OutType,
+): Map<Key, OutType> {
+  const lookup = new Map<Key, OutType>();
+  for (const entity of list) {
+    // get a correct key value
+    const key = getKeyValue(entity, keyName) as Key;
+    // these 3 steps are to set up the map, the map differs according to the reducer.
+    const original = lookup.get(key);
+    const reduced = reducer(original, entity);
+    lookup.set(key, reduced);
+  }
+  return lookup;
+}
+
+/**
+ * Returns value of a keyName. Aims to resolve ObjectId problem of Mongo.
+ *
+ * @param model - target model
+ * @param keyName - target key that gets the value from
+ */
+export function getKeyValue(model: AnyObject, keyName: string) {
+  return normalizeKey(model[keyName]);
+}
+
+/**
+ * Workaround for MongoDB, where the connector returns ObjectID
+ * values even for properties configured with "type: string".
+ *
+ * @param rawKey
+ */
+export function normalizeKey(rawKey: unknown) {
+  if (isBsonType(rawKey)) {
+    return rawKey.toString();
+  }
+  return rawKey;
+}
+
+/**
+ * Returns an array of instances. For HasMany relation usage.
+ *
+ * @param acc
+ * @param it
+ */
+export function reduceAsArray<T>(acc: T[] | undefined, it: T) {
+  if (acc) acc.push(it);
+  else acc = [it];
+  return acc;
+}
+/**
+ * Returns a single of an instance. For HasOne and BelongsTo relation usage.
+ *
+ * @param _acc
+ * @param it
+ */
+export function reduceAsSingleItem<T>(_acc: T | undefined, it: T) {
+  return it;
+}
+
+/**
+ * Dedupe an array
+ * @param input - an array of sourceIds
+ * @returns an array with unique items
+ */
+export function deduplicate<T>(input: T[]): T[] {
+  const uniqArray: T[] = [];
+  if (!input) {
+    return uniqArray;
+  }
+  assert(Array.isArray(input), 'array argument is required');
+
+  const comparableArray = input.map(item => normalizeKey(item));
+  for (let i = 0, n = comparableArray.length; i < n; i++) {
+    if (comparableArray.indexOf(comparableArray[i]) === i) {
+      uniqArray.push(input[i]);
+    }
+  }
+  return uniqArray;
+}
+
+/**
+ * Checks if the value is BsonType (mongodb)
+ * It uses a general way to check the type ,so that it can detect
+ * different versions of bson that might be used in the code base.
+ * Might need to update in the future.
+ *
+ * @param value
+ */
+export function isBsonType(value: unknown): value is object {
+  if (typeof value !== 'object' || !value) return false;
+
+  // bson@1.x stores _bsontype on ObjectID instance, bson@4.x on prototype
+  return check(value) || check(value.constructor.prototype);
+
+  function check(target: unknown) {
+    return Object.prototype.hasOwnProperty.call(target, '_bsontype');
+  }
+}

package/src/relations/relation.types.ts

@@ -0,0 +1,180 @@
+// Copyright IBM Corp. 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 {InclusionFilter} from '@loopback/filter';
+import {Options} from '../common-types';
+import {Entity} from '../model';
+import {TypeResolver} from '../type-resolver';
+
+export enum RelationType {
+  belongsTo = 'belongsTo',
+  hasOne = 'hasOne',
+  hasMany = 'hasMany',
+  embedsOne = 'embedsOne',
+  embedsMany = 'embedsMany',
+  referencesOne = 'referencesOne',
+  referencesMany = 'referencesMany',
+}
+
+export interface RelationDefinitionBase {
+  /**
+   * The type of the relation, must be one of RelationType values.
+   */
+  type: RelationType;
+
+  /**
+   * True for relations targeting multiple instances (e.g. HasMany),
+   * false for relations with a single target (e.g. BelongsTo, HasOne).
+   * This property is needed by OpenAPI/JSON Schema generator.
+   */
+  targetsMany: boolean;
+
+  /**
+   * The relation name, typically matching the name of the accessor property
+   * defined on the source model. For example "orders" or "customer".
+   */
+  name: string;
+
+  /**
+   * The source model of this relation.
+   *
+   * E.g. when a Customer has many Order instances, then Customer is the source.
+   */
+  source: typeof Entity;
+
+  /**
+   * The target model of this relation.
+   *
+   * E.g. when a Customer has many Order instances, then Order is the target.
+   */
+  target: TypeResolver<Entity, typeof Entity>;
+}
+
+/**
+ * HasManyDefinition defines one-to-many relations and also possible defines
+ * many-to-many relations with through models.
+ */
+export interface HasManyDefinition extends RelationDefinitionBase {
+  type: RelationType.hasMany;
+  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.
+   *
+   * 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;
+
+  /**
+   * Description of the through model of the hasManyThrough relation.
+   *
+   * 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.
+   *
+   * E.g a Category has many Products, and a Product can have many Categories.
+   * CategoryProductLink can be the through model.
+   * Such a through model has information of foreign keys of the source model(Category) and the target model(Product).
+   *
+   * 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.
+   */
+  through?: {
+    /**
+     * The through model of this relation.
+     *
+     * E.g. when a Category has many CategoryProductLink instances and a Product has many CategoryProductLink instances,
+     * then CategoryProductLink is through.
+     */
+    model: TypeResolver<Entity, typeof Entity>;
+
+    /**
+     * The foreign key of the source model defined in the through model, e.g. CategoryProductLink#categoryId
+     */
+    keyFrom?: string;
+
+    /**
+     * The foreign key of the target model defined in the through model, e.g. CategoryProductLink#productId
+     */
+    keyTo?: string;
+  };
+}
+
+export interface BelongsToDefinition extends RelationDefinitionBase {
+  type: RelationType.belongsTo;
+  targetsMany: false;
+
+  /*
+   * The foreign key in the source model, e.g. Order#customerId.
+   */
+  keyFrom?: string;
+
+  /*
+   * The primary key of the target model, e.g Customer#id.
+   */
+  keyTo?: string;
+}
+
+export interface HasOneDefinition extends RelationDefinitionBase {
+  type: RelationType.hasOne;
+  targetsMany: false;
+
+  /**
+   * 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;
+}
+
+/**
+ * A union type describing all possible Relation metadata objects.
+ */
+export type RelationMetadata =
+  | HasManyDefinition
+  | BelongsToDefinition
+  | HasOneDefinition
+  // TODO(bajtos) add other relation types and remove RelationDefinitionBase once
+  // all relation types are covered.
+  | RelationDefinitionBase;
+
+// Re-export Getter so that users don't have to import from @loopback/context
+export {Getter} from '@loopback/core';
+
+/**
+ * @returns An array of resolved values, the items must be ordered in the same
+ * way as `sourceEntities`. The resolved value can be one of:
+ * - `undefined` when no target model(s) were found
+ * - `Entity` for relations targeting a single model
+ * - `Entity[]` for relations targeting multiple models
+ */
+export type InclusionResolver<S extends Entity, T extends Entity> = (
+  /**
+   * List of source models as returned by the first database query.
+   */
+  sourceEntities: S[],
+  /**
+   * Inclusion requested by the user (e.g. scope constraints to apply).
+   */
+  inclusion: InclusionFilter,
+  /**
+   * Generic options object, e.g. carrying the Transaction object.
+   */
+  options?: Options,
+) => Promise<(T | undefined)[] | (T[] | undefined)[]>;