@loopback/repository 4.0.0-alpha.8 → 4.1.0

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

@@ -0,0 +1,78 @@
+// 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 debugFactory from 'debug';
+import {camelCase} from 'lodash';
+import {InvalidRelationError} from '../../errors';
+import {isTypeResolver} from '../../type-resolver';
+import {BelongsToDefinition, RelationType} from '../relation.types';
+
+const debug = debugFactory('loopback:repository:relations:belongs-to:helpers');
+
+/**
+ * Relation definition with optional metadata (e.g. `keyTo`) filled in.
+ * @internal
+ */
+export type BelongsToResolvedDefinition = BelongsToDefinition & {
+  keyFrom: string;
+  keyTo: string;
+};
+
+/**
+ * Resolves given belongsTo metadata if target is specified to be a resolver.
+ * Mainly used to infer what the `keyTo` property should be from the target's
+ * property id metadata
+ * @param relationMeta - belongsTo metadata to resolve
+ * @internal
+ */
+export function resolveBelongsToMetadata(relationMeta: BelongsToDefinition) {
+  if ((relationMeta.type as RelationType) !== RelationType.belongsTo) {
+    const reason = 'relation type must be BelongsTo';
+    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);
+  }
+
+  const targetModel = relationMeta.target();
+  const targetName = targetModel.modelName;
+  debug('Resolved model %s from given metadata: %o', targetName, targetModel);
+
+  let keyFrom;
+  if (
+    relationMeta.keyFrom &&
+    relationMeta.source.definition.properties[relationMeta.keyFrom]
+  ) {
+    keyFrom = relationMeta.keyFrom;
+  } else {
+    keyFrom = camelCase(targetName + '_id');
+  }
+
+  const targetProperties = targetModel.definition.properties;
+  debug('relation metadata from %o: %o', targetName, targetProperties);
+
+  if (relationMeta.keyTo && targetProperties[relationMeta.keyTo]) {
+    // The explicit cast is needed because of a limitation of type inference
+    return Object.assign(relationMeta, {
+      keyFrom,
+    }) as BelongsToResolvedDefinition;
+  }
+
+  const targetPrimaryKey = targetModel.definition.idProperties()[0];
+  if (!targetPrimaryKey) {
+    const reason = `${targetName} does not have any primary key (id property)`;
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  return Object.assign(relationMeta, {keyFrom, keyTo: targetPrimaryKey});
+}

package/src/relations/belongs-to/belongs-to.inclusion-resolver.ts

@@ -0,0 +1,71 @@
+// 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 {Filter, InclusionFilter} from '@loopback/filter';
+import {AnyObject, Options} from '../../common-types';
+import {Entity} from '../../model';
+import {EntityCrudRepository} from '../../repositories';
+import {
+  deduplicate,
+  findByForeignKeys,
+  flattenTargetsOfOneToOneRelation,
+  StringKeyOf,
+} from '../relation.helpers';
+import {
+  BelongsToDefinition,
+  Getter,
+  InclusionResolver,
+} from '../relation.types';
+import {resolveBelongsToMetadata} from './belongs-to.helpers';
+
+/**
+ * Creates InclusionResolver for BelongsTo relation.
+ * Notice that this function only generates the inclusionResolver.
+ * It doesn't register it for the source repository.
+ *
+ * Notice: scope field for inclusion is not supported yet
+ *
+ * @param meta - resolved BelongsToMetadata
+ * @param getTargetRepo - target repository i.e where related instances are
+ */
+export function createBelongsToInclusionResolver<
+  Target extends Entity,
+  TargetID,
+  TargetRelations extends object,
+>(
+  meta: BelongsToDefinition,
+  getTargetRepo: Getter<
+    EntityCrudRepository<Target, TargetID, TargetRelations>
+  >,
+): InclusionResolver<Entity, Target> {
+  const relationMeta = resolveBelongsToMetadata(meta);
+
+  return async function fetchIncludedModels(
+    entities: Entity[],
+    inclusion: InclusionFilter,
+    options?: Options,
+  ): Promise<((Target & TargetRelations) | undefined)[]> {
+    if (!entities.length) return [];
+
+    const sourceKey = relationMeta.keyFrom;
+    const sourceIds = entities.map(e => (e as AnyObject)[sourceKey]);
+    const targetKey = relationMeta.keyTo as StringKeyOf<Target>;
+    const dedupedSourceIds = deduplicate(sourceIds);
+
+    const scope =
+      typeof inclusion === 'string' ? {} : (inclusion.scope as Filter<Target>);
+
+    const targetRepo = await getTargetRepo();
+    const targetsFound = await findByForeignKeys(
+      targetRepo,
+      targetKey,
+      dedupedSourceIds.filter(e => e),
+      scope,
+      options,
+    );
+
+    return flattenTargetsOfOneToOneRelation(sourceIds, targetsFound, targetKey);
+  };
+}

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

@@ -0,0 +1,55 @@
+// 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 {Getter} from '@loopback/core';
+import {DataObject, Options} from '../../common-types';
+import {EntityNotFoundError} from '../../errors';
+import {Entity} from '../../model';
+import {constrainFilter, EntityCrudRepository} from '../../repositories';
+
+/**
+ * CRUD operations for a target repository of a BelongsTo relation
+ */
+export interface BelongsToRepository<Target extends Entity> {
+  /**
+   * Gets the target model instance
+   * @param options
+   * @returns A promise resolved with the target object or rejected
+   * with an EntityNotFoundError when target model instance was not found.
+   */
+  get(options?: Options): Promise<Target>;
+}
+
+export class DefaultBelongsToRepository<
+  TargetEntity extends Entity,
+  TargetId,
+  TargetRepository extends EntityCrudRepository<TargetEntity, TargetId>,
+> implements BelongsToRepository<TargetEntity>
+{
+  /**
+   * Constructor of DefaultBelongsToEntityCrudRepository
+   * @param getTargetRepository - the getter of the related target model repository instance
+   * @param constraint - the key value pair representing foreign key name to constrain
+   * the target repository instance
+   */
+  constructor(
+    public getTargetRepository: Getter<TargetRepository>,
+    public constraint: DataObject<TargetEntity>,
+  ) {}
+
+  async get(options?: Options): Promise<TargetEntity> {
+    const targetRepo = await this.getTargetRepository();
+    const result = await targetRepo.find(
+      constrainFilter(undefined, this.constraint),
+      options,
+    );
+    if (!result.length) {
+      // We don't have a direct access to the foreign key value here :(
+      const id = 'constraint ' + JSON.stringify(this.constraint);
+      throw new EntityNotFoundError(targetRepo.entityClass, id);
+    }
+    return result[0];
+  }
+}

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

@@ -0,0 +1,9 @@
+// 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
+
+export * from './belongs-to.decorator';
+export * from './belongs-to.repository';
+export * from './belongs-to.accessor';
+export * from './belongs-to.inclusion-resolver';

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

@@ -0,0 +1,361 @@
+// 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 debugFactory from 'debug';
+import {camelCase} from 'lodash';
+import {
+  DataObject,
+  deduplicate,
+  Entity,
+  HasManyDefinition,
+  InvalidRelationError,
+  isTypeResolver,
+} from '../..';
+import {resolveHasManyMetaHelper} from './has-many.helpers';
+
+const debug = debugFactory(
+  'loopback:repository:relations:has-many-through:helpers',
+);
+
+export type HasManyThroughResolvedDefinition = HasManyDefinition & {
+  keyTo: string;
+  keyFrom: string;
+  through: {
+    keyTo: string;
+    keyFrom: string;
+  };
+};
+
+/**
+ * Creates target constraint based on through models
+ * @param relationMeta - resolved hasManyThrough metadata
+ * @param throughInstances - an array of through instances
+ *
+ * @example
+ * ```ts
+ * const resolvedMetadata = {
+ *  // .. other props
+ *  keyFrom: 'id',
+ *  keyTo: 'id',
+ *  through: {
+ *    model: () => CategoryProductLink,
+ *    keyFrom: 'categoryId',
+ *    keyTo: 'productId',
+ *  },
+ * };
+ * createTargetConstraintFromThrough(resolvedMetadata,[{
+        id: 2,
+        categoryId: 2,
+        productId: 8,
+      }]);
+ * >>> {id: 8}
+ * createTargetConstraintFromThrough(resolvedMetadata, [
+      {
+        id: 2,
+        categoryId: 2,
+        productId: 8,
+      }, {
+        id: 1,
+        categoryId: 2,
+        productId: 9,
+      }
+  ]);
+
+  >>> {id: {inq: [9, 8]}}
+ * ```
+ */
+export function createTargetConstraintFromThrough<
+  Target extends Entity,
+  Through extends Entity,
+>(
+  relationMeta: HasManyThroughResolvedDefinition,
+  throughInstances: Through[],
+): DataObject<Target> {
+  const fkValues = getTargetKeysFromThroughModels(
+    relationMeta,
+    throughInstances,
+  );
+  const targetPrimaryKey = relationMeta.keyTo;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const constraint: any = {
+    [targetPrimaryKey]: fkValues.length === 1 ? fkValues[0] : {inq: fkValues},
+  };
+  return constraint;
+}
+
+/**
+ * Returns an array of target fks of the given throughInstances.
+ *
+ * @param relationMeta - resolved hasManyThrough metadata
+ * @param throughInstances - an array of through instances
+ *
+ * @example
+ * ```ts
+ * const resolvedMetadata = {
+ *  // .. other props
+ *  keyFrom: 'id',
+ *  keyTo: 'id',
+ *  through: {
+ *    model: () => CategoryProductLink,
+ *    keyFrom: 'categoryId',
+ *    keyTo: 'productId',
+ *  },
+ * };
+ * getTargetKeysFromThroughModels(resolvedMetadata,[{
+        id: 2,
+        categoryId: 2,
+        productId: 8,
+      }]);
+ * >>> [8]
+ * getTargetKeysFromThroughModels(resolvedMetadata, [
+      {
+        id: 2,
+        categoryId: 2,
+        productId: 8,
+      }, {
+        id: 1,
+        categoryId: 2,
+        productId: 9,
+      }
+  ]);
+  >>> [8, 9]
+ */
+export function getTargetKeysFromThroughModels<
+  Through extends Entity,
+  TargetID,
+>(
+  relationMeta: HasManyThroughResolvedDefinition,
+  throughInstances: Through[],
+): TargetID[] {
+  const targetFkName = relationMeta.through.keyTo;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let fkValues: any = throughInstances.map(
+    (throughInstance: Through) =>
+      throughInstance[targetFkName as keyof Through],
+  );
+  fkValues = deduplicate(fkValues);
+  return fkValues as TargetID[];
+}
+
+/**
+ * Creates through constraint based on the source key
+ *
+ * @param relationMeta - resolved hasManyThrough metadata
+ * @param fkValue - foreign key of the source instance
+ * @internal
+ *
+ * @example
+ * ```ts
+ * const resolvedMetadata = {
+ *  // .. other props
+ *  keyFrom: 'id',
+ *  keyTo: 'id',
+ *  through: {
+ *    model: () => CategoryProductLink,
+ *    keyFrom: 'categoryId',
+ *    keyTo: 'productId',
+ *  },
+ * };
+ * createThroughConstraintFromSource(resolvedMetadata, 1);
+ *
+ * >>> {categoryId: 1}
+ * ```
+ */
+export function createThroughConstraintFromSource<
+  Through extends Entity,
+  SourceID,
+>(
+  relationMeta: HasManyThroughResolvedDefinition,
+  fkValue: SourceID,
+): DataObject<Through> {
+  const sourceFkName = relationMeta.through.keyFrom;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const constraint: any = {[sourceFkName]: fkValue};
+  return constraint;
+}
+
+/**
+ * Returns an array of target ids of the given target instances.
+ *
+ * @param relationMeta - resolved hasManyThrough metadata
+ * @param targetInstances - an array of target instances
+ *
+ * @example
+ * ```ts
+ * const resolvedMetadata = {
+ *  // .. other props
+ *  keyFrom: 'id',
+ *  keyTo: 'id',
+ *  through: {
+ *    model: () => CategoryProductLink,
+ *    keyFrom: 'categoryId',
+ *    keyTo: 'productId',
+ *  },
+ * };
+ * getTargetKeysFromTargetModels(resolvedMetadata,[{
+        id: 2,
+        des: 'a target',
+      }]);
+ * >>> [2]
+ * getTargetKeysFromTargetModels(resolvedMetadata, [
+      {
+        id: 2,
+        des: 'a target',
+      }, {
+        id: 1,
+        des: 'a target',
+      }
+  ]);
+  >>> [2, 1]
+ */
+export function getTargetIdsFromTargetModels<Target extends Entity, TargetID>(
+  relationMeta: HasManyThroughResolvedDefinition,
+  targetInstances: Target[],
+): TargetID[] {
+  const targetId = relationMeta.keyTo;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let ids = [] as any;
+  ids = targetInstances.map(
+    (targetInstance: Target) => targetInstance[targetId as keyof Target],
+  );
+  ids = deduplicate(ids);
+  return ids as TargetID[];
+}
+
+/**
+ * Creates through constraint based on the target foreign key
+ *
+ * @param relationMeta - resolved hasManyThrough metadata
+ * @param fkValue an array of the target instance foreign keys
+ * @internal
+ *
+ * @example
+ * ```ts
+ * const resolvedMetadata = {
+ *  // .. other props
+ *  keyFrom: 'id',
+ *  keyTo: 'id',
+ *  through: {
+ *    model: () => CategoryProductLink,
+ *    keyFrom: 'categoryId',
+ *    keyTo: 'productId',
+ *  },
+ * };
+ * createThroughConstraintFromTarget(resolvedMetadata, [3]);
+ *
+ * >>> {productId: 3}
+ *
+ * createThroughConstraintFromTarget(resolvedMetadata, [3,4]);
+ *
+ * >>> {productId: {inq:[3,4]}}
+ */
+export function createThroughConstraintFromTarget<
+  Through extends Entity,
+  TargetID,
+>(
+  relationMeta: HasManyThroughResolvedDefinition,
+  fkValues: TargetID[],
+): DataObject<Through> {
+  if (fkValues === undefined || fkValues.length === 0) {
+    throw new Error('"fkValue" must be provided');
+  }
+  const targetFkName = relationMeta.through.keyTo;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const constraint: any =
+    fkValues.length === 1
+      ? {[targetFkName]: fkValues[0]}
+      : {[targetFkName]: {inq: fkValues}};
+
+  return constraint as DataObject<Through>;
+}
+
+/**
+ * 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 explicit 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-through.inclusion-resolver.ts

@@ -0,0 +1,135 @@
+// 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 {Filter, InclusionFilter} from '@loopback/filter';
+import debugFactory from 'debug';
+import {AnyObject, Options} from '../../common-types';
+import {Entity} from '../../model';
+import {EntityCrudRepository} from '../../repositories';
+import {
+  findByForeignKeys,
+  flattenTargetsOfOneToManyRelation,
+  StringKeyOf,
+} from '../relation.helpers';
+import {Getter, HasManyDefinition, InclusionResolver} from '../relation.types';
+import {resolveHasManyMetadata} from './has-many.helpers';
+
+const debug = debugFactory(
+  'loopback:repository:relations:has-many-through:inclusion-resolver',
+);
+
+/**
+ * Creates InclusionResolver for HasManyThrough relation.
+ * Notice that this function only generates the inclusionResolver.
+ * It doesn't register it for the source repository.
+ *
+ *
+ * @param meta - metadata of the hasMany relation (including through)
+ * @param getThroughRepo - through repository getter i.e. where through
+ * instances are
+ * @param getTargetRepo - target repository getter i.e where target instances
+ * are
+ */
+export function createHasManyThroughInclusionResolver<
+  Through extends Entity,
+  ThroughID,
+  ThroughRelations extends object,
+  Target extends Entity,
+  TargetID,
+  TargetRelations extends object,
+>(
+  meta: HasManyDefinition,
+  getThroughRepo: Getter<
+    EntityCrudRepository<Through, ThroughID, ThroughRelations>
+  >,
+  getTargetRepo: Getter<
+    EntityCrudRepository<Target, TargetID, TargetRelations>
+  >,
+): InclusionResolver<Entity, Target> {
+  const relationMeta = resolveHasManyMetadata(meta);
+
+  return async function fetchHasManyThroughModels(
+    entities: Entity[],
+    inclusion: InclusionFilter,
+    options?: Options,
+  ): Promise<((Target & TargetRelations)[] | undefined)[]> {
+    if (!entities.length) return [];
+
+    debug('Fetching target models for entities:', entities);
+    debug('Relation metadata:', relationMeta);
+
+    const sourceKey = relationMeta.keyFrom;
+    const sourceIds = entities.map(e => (e as AnyObject)[sourceKey]);
+    const targetKey = relationMeta.keyTo as StringKeyOf<Target>;
+    if (!relationMeta.through) {
+      throw new Error(
+        `relationMeta.through must be defined on ${relationMeta}`,
+      );
+    }
+    const throughKeyTo = relationMeta.through.keyTo as StringKeyOf<Through>;
+    const throughKeyFrom = relationMeta.through.keyFrom as StringKeyOf<Through>;
+
+    debug('Parameters:', {
+      sourceKey,
+      sourceIds,
+      targetKey,
+      throughKeyTo,
+      throughKeyFrom,
+    });
+
+    debug(
+      'sourceId types',
+      sourceIds.map(i => typeof i),
+    );
+
+    const throughRepo = await getThroughRepo();
+    const targetRepo = await getTargetRepo();
+
+    // find through models
+    const throughFound = await findByForeignKeys(
+      throughRepo,
+      throughKeyFrom,
+      sourceIds,
+      {}, // scope will be applied at the target level
+      options,
+    );
+
+    const throughResult = flattenTargetsOfOneToManyRelation(
+      sourceIds,
+      throughFound,
+      throughKeyFrom,
+    );
+
+    const result = [];
+
+    const scope =
+      typeof inclusion === 'string' ? {} : (inclusion.scope as Filter<Target>);
+
+    // convert from through entities to the target entities
+    for (const entityList of throughResult) {
+      if (entityList) {
+        // get target ids from the through entities by foreign key
+        const targetIds = entityList.map(entity => entity[throughKeyTo]);
+
+        // the explicit types and casts are needed
+        const targetEntityList = await findByForeignKeys<
+          Target,
+          TargetRelations,
+          StringKeyOf<Target>
+        >(targetRepo, targetKey, targetIds as unknown as [], scope, {
+          ...options,
+          isThroughModelInclude: true,
+        });
+        result.push(targetEntityList);
+      } else {
+        // no entities found, add undefined to results
+        result.push(entityList);
+      }
+    }
+
+    debug('fetchHasManyThroughModels result', result);
+    return result;
+  };
+}