@loopback/repository 4.0.0-alpha.7 → 4.0.1

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

@@ -0,0 +1,76 @@
+// 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 debugFactory from 'debug';
+import {DataObject} from '../../common-types';
+import {Entity} from '../../model';
+import {EntityCrudRepository} from '../../repositories';
+import {Getter, HasManyDefinition, InclusionResolver} from '../relation.types';
+import {resolveHasManyMetadata} from './has-many.helpers';
+import {createHasManyInclusionResolver} from './has-many.inclusion-resolver';
+import {
+  DefaultHasManyRepository,
+  HasManyRepository,
+} from './has-many.repository';
+
+const debug = debugFactory(
+  'loopback:repository:relations:has-many:repository-factory',
+);
+
+export interface HasManyRepositoryFactory<
+  Target extends Entity,
+  ForeignKeyType,
+> {
+  /**
+   * Invoke the function to obtain HasManyRepository.
+   */
+  (fkValue: ForeignKeyType): HasManyRepository<Target>;
+
+  /**
+   * Use `resolver` property to obtain an InclusionResolver for this relation.
+   */
+  inclusionResolver: InclusionResolver<Entity, Target>;
+}
+
+/**
+ * Enforces a constraint on a repository based on a relationship contract
+ * between models. For example, if a Customer model is related to an Order model
+ * via a HasMany relation, then, the relational repository returned by the
+ * factory function would be constrained by a Customer model instance's id(s).
+ *
+ * @param relationMetadata - The relation metadata used to describe the
+ * relationship and determine how to apply the constraint.
+ * @param targetRepositoryGetter - The repository which represents the target model of a
+ * relation attached to a datasource.
+ * @returns The factory function which accepts a foreign key value to constrain
+ * the given target repository
+ */
+export function createHasManyRepositoryFactory<
+  Target extends Entity,
+  TargetID,
+  ForeignKeyType,
+>(
+  relationMetadata: HasManyDefinition,
+  targetRepositoryGetter: Getter<EntityCrudRepository<Target, TargetID>>,
+): HasManyRepositoryFactory<Target, ForeignKeyType> {
+  const meta = resolveHasManyMetadata(relationMetadata);
+  debug('Resolved HasMany relation metadata: %o', meta);
+  const result: HasManyRepositoryFactory<Target, ForeignKeyType> = function (
+    fkValue: ForeignKeyType,
+  ) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const constraint: any = {[meta.keyTo]: fkValue};
+    return new DefaultHasManyRepository<
+      Target,
+      TargetID,
+      EntityCrudRepository<Target, TargetID>
+    >(targetRepositoryGetter, constraint as DataObject<Target>);
+  };
+  result.inclusionResolver = createHasManyInclusionResolver(
+    meta,
+    targetRepositoryGetter,
+  );
+  return result;
+}

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

@@ -0,0 +1,118 @@
+// 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 {Filter, Where} from '@loopback/filter';
+import {Count, DataObject, Options} from '../../common-types';
+import {Entity} from '../../model';
+import {
+  constrainDataObject,
+  constrainFilter,
+  constrainWhere,
+  EntityCrudRepository,
+} from '../../repositories';
+
+/**
+ * CRUD operations for a target repository of a HasMany relation
+ */
+export interface HasManyRepository<Target 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,
+  ): 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): 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): 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,
+  ): Promise<Count>;
+}
+
+export class DefaultHasManyRepository<
+  TargetEntity extends Entity,
+  TargetID,
+  TargetRepository extends EntityCrudRepository<TargetEntity, TargetID>,
+> implements HasManyRepository<TargetEntity>
+{
+  /**
+   * Constructor of DefaultHasManyEntityCrudRepository
+   * @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 create(
+    targetModelData: DataObject<TargetEntity>,
+    options?: Options,
+  ): Promise<TargetEntity> {
+    const targetRepository = await this.getTargetRepository();
+    return targetRepository.create(
+      constrainDataObject(targetModelData, this.constraint),
+      options,
+    );
+  }
+
+  async find(
+    filter?: Filter<TargetEntity>,
+    options?: Options,
+  ): Promise<TargetEntity[]> {
+    const targetRepository = await this.getTargetRepository();
+    return targetRepository.find(
+      constrainFilter(filter, this.constraint),
+      options,
+    );
+  }
+
+  async delete(where?: Where<TargetEntity>, options?: Options): Promise<Count> {
+    const targetRepository = await this.getTargetRepository();
+    return targetRepository.deleteAll(
+      constrainWhere(where, this.constraint as Where<TargetEntity>),
+      options,
+    );
+  }
+
+  async patch(
+    dataObject: DataObject<TargetEntity>,
+    where?: Where<TargetEntity>,
+    options?: Options,
+  ): Promise<Count> {
+    const targetRepository = await this.getTargetRepository();
+    return targetRepository.updateAll(
+      constrainDataObject(dataObject, this.constraint),
+      constrainWhere(where, this.constraint as Where<TargetEntity>),
+      options,
+    );
+  }
+}

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

@@ -0,0 +1,11 @@
+// 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 './has-many.repository-factory';
+export * from './has-many-through.repository-factory';
+export * from './has-many-through.repository';
+export * from './has-many.decorator';
+export * from './has-many.inclusion-resolver';
+export * from './has-many.repository';

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

@@ -0,0 +1,40 @@
+// 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 {Entity, EntityResolver} from '../../model';
+import {relation} from '../relation.decorator';
+import {HasOneDefinition, RelationType} from '../relation.types';
+
+/*
+ * Decorator for hasOne
+ * infers foreign key name from target model name unless explicitly specified
+ * @param targetResolver - Target model for hasOne relation
+ * @param definition - Optional metadata for setting up hasOne relation
+ * @returns A property decorator
+ */
+export function hasOne<T extends Entity>(
+  targetResolver: EntityResolver<T>,
+  definition?: Partial<HasOneDefinition>,
+) {
+  return function (decoratedTarget: object, key: string) {
+    // property.array(targetResolver)(decoratedTarget, key);
+
+    const meta: HasOneDefinition = Object.assign(
+      // default values, can be customized by the caller
+      {},
+      // properties provided by the caller
+      definition,
+      // properties enforced by the decorator
+      {
+        type: RelationType.hasOne,
+        targetsMany: false,
+        name: key,
+        source: decoratedTarget.constructor,
+        target: targetResolver,
+      },
+    );
+    relation(meta)(decoratedTarget, key);
+  };
+}

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

@@ -0,0 +1,84 @@
+// 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 debugFactory from 'debug';
+import {camelCase} from 'lodash';
+import {InvalidRelationError} from '../../errors';
+import {isTypeResolver} from '../../type-resolver';
+import {HasOneDefinition, RelationType} from '../relation.types';
+
+const debug = debugFactory('loopback:repository:relations:has-one:helpers');
+
+/**
+ * Relation definition with optional metadata (e.g. `keyTo`) filled in.
+ * @internal
+ */
+export type HasOneResolvedDefinition = HasOneDefinition & {
+  keyFrom: string;
+  keyTo: string;
+};
+
+/**
+ * Resolves given hasOne metadata if target is specified to be a resolver.
+ * Mainly used to infer what the `keyTo` property should be from the target's
+ * hasOne metadata
+ * @param relationMeta - hasOne metadata to resolve
+ * @internal
+ */
+export function resolveHasOneMetadata(
+  relationMeta: HasOneDefinition,
+): HasOneResolvedDefinition {
+  if ((relationMeta.type as RelationType) !== RelationType.hasOne) {
+    const reason = 'relation type must be HasOne';
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  if (!isTypeResolver(relationMeta.target)) {
+    const reason = 'target must be a type resolver';
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  const targetModel = relationMeta.target();
+  const targetModelProperties = 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 HasOneResolvedDefinition;
+  }
+
+  debug(
+    'Resolved model %s from given metadata: %o',
+    targetModel.modelName,
+    targetModel,
+  );
+  const defaultFkName = camelCase(sourceModel.modelName + '_id');
+  const hasDefaultFkProperty = targetModelProperties[defaultFkName];
+
+  if (!hasDefaultFkProperty) {
+    const reason = `target model ${targetModel.name} is missing definition of foreign key ${defaultFkName}`;
+    throw new InvalidRelationError(reason, relationMeta);
+  }
+
+  return Object.assign(relationMeta, {keyFrom, keyTo: defaultFkName});
+}

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

@@ -0,0 +1,65 @@
+// 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 {
+  findByForeignKeys,
+  flattenTargetsOfOneToOneRelation,
+  StringKeyOf,
+} from '../relation.helpers';
+import {Getter, HasOneDefinition, InclusionResolver} from '../relation.types';
+import {resolveHasOneMetadata} from './has-one.helpers';
+
+/**
+ * Creates InclusionResolver for HasOne 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
+ * @param getTargetRepo
+ */
+export function createHasOneInclusionResolver<
+  Target extends Entity,
+  TargetID,
+  TargetRelations extends object,
+>(
+  meta: HasOneDefinition,
+  getTargetRepo: Getter<
+    EntityCrudRepository<Target, TargetID, TargetRelations>
+  >,
+): InclusionResolver<Entity, Target> {
+  const relationMeta = resolveHasOneMetadata(meta);
+
+  return async function fetchHasOneModel(
+    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 scope =
+      typeof inclusion === 'string' ? {} : (inclusion.scope as Filter<Target>);
+
+    const targetRepo = await getTargetRepo();
+    const targetsFound = await findByForeignKeys(
+      targetRepo,
+      targetKey,
+      sourceIds,
+      scope,
+      options,
+    );
+
+    return flattenTargetsOfOneToOneRelation(sourceIds, targetsFound, targetKey);
+  };
+}

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

@@ -0,0 +1,72 @@
+// 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 debugFactory from 'debug';
+import {DataObject} from '../../common-types';
+import {Entity} from '../../model';
+import {EntityCrudRepository} from '../../repositories';
+import {Getter, HasOneDefinition, InclusionResolver} from '../relation.types';
+import {resolveHasOneMetadata} from './has-one.helpers';
+import {createHasOneInclusionResolver} from './has-one.inclusion-resolver';
+import {DefaultHasOneRepository, HasOneRepository} from './has-one.repository';
+
+const debug = debugFactory(
+  'loopback:repository:relations:has-one:repository-factory',
+);
+
+export interface HasOneRepositoryFactory<
+  Target extends Entity,
+  ForeignKeyType,
+> {
+  /**
+   * Invoke the function to obtain HasOneRepository.
+   */
+  (fkValue: ForeignKeyType): HasOneRepository<Target>;
+
+  /**
+   * Use `resolver` property to obtain an InclusionResolver for this relation.
+   */
+  inclusionResolver: InclusionResolver<Entity, Target>;
+}
+/**
+ * Enforces a constraint on a repository based on a relationship contract
+ * between models. For example, if a Customer model is related to an Address model
+ * via a HasOne relation, then, the relational repository returned by the
+ * factory function would be constrained by a Customer model instance's id(s).
+ *
+ * @param relationMetadata - The relation metadata used to describe the
+ * relationship and determine how to apply the constraint.
+ * @param targetRepositoryGetter - The repository which represents the target model of a
+ * relation attached to a datasource.
+ * @returns The factory function which accepts a foreign key value to constrain
+ * the given target repository
+ */
+export function createHasOneRepositoryFactory<
+  Target extends Entity,
+  TargetID,
+  ForeignKeyType,
+>(
+  relationMetadata: HasOneDefinition,
+  targetRepositoryGetter: Getter<EntityCrudRepository<Target, TargetID>>,
+): HasOneRepositoryFactory<Target, ForeignKeyType> {
+  const meta = resolveHasOneMetadata(relationMetadata);
+  debug('Resolved HasOne relation metadata: %o', meta);
+  const result: HasOneRepositoryFactory<Target, ForeignKeyType> = function (
+    fkValue: ForeignKeyType,
+  ) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const constraint: any = {[meta.keyTo]: fkValue};
+    return new DefaultHasOneRepository<
+      Target,
+      TargetID,
+      EntityCrudRepository<Target, TargetID>
+    >(targetRepositoryGetter, constraint as DataObject<Target>);
+  };
+  result.inclusionResolver = createHasOneInclusionResolver(
+    meta,
+    targetRepositoryGetter,
+  );
+  return result;
+}

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

@@ -0,0 +1,127 @@
+// 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 {Filter} from '@loopback/filter';
+import {Count, DataObject, Options} from '../../common-types';
+import {EntityNotFoundError} from '../../errors';
+import {Entity} from '../../model';
+import {
+  constrainDataObject,
+  constrainFilter,
+  constrainWhere,
+  EntityCrudRepository,
+} from '../../repositories';
+
+/**
+ * CRUD operations for a target repository of a HasMany relation
+ */
+export interface HasOneRepository<Target 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,
+  ): Promise<Target>;
+
+  /**
+   * Find the only target model instance that belongs to the declaring model.
+   * @param filter - Query filter without a Where condition
+   * @param options - Options for the operations
+   * @returns A promise resolved with the target object or rejected
+   * with an EntityNotFoundError when target model instance was not found.
+   */
+  get(
+    filter?: Pick<Filter<Target>, Exclude<keyof Filter<Target>, 'where'>>,
+    options?: Options,
+  ): Promise<Target>;
+
+  /**
+   * Delete the related target model instance
+   * @param options
+   * @returns A promise which resolves the deleted target model instances
+   */
+  delete(options?: Options): Promise<Count>;
+
+  /**
+   * Patch the  related target model instance
+   * @param dataObject - The target model fields and their new values to patch
+   * @param options
+   * @returns A promise which resolves the patched target model instances
+   */
+  patch(dataObject: DataObject<Target>, options?: Options): Promise<Count>;
+}
+
+export class DefaultHasOneRepository<
+  TargetEntity extends Entity,
+  TargetID,
+  TargetRepository extends EntityCrudRepository<TargetEntity, TargetID>,
+> implements HasOneRepository<TargetEntity>
+{
+  /**
+   * Constructor of DefaultHasOneEntityCrudRepository
+   * @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 create(
+    targetModelData: DataObject<TargetEntity>,
+    options?: Options,
+  ): Promise<TargetEntity> {
+    const targetRepository = await this.getTargetRepository();
+    return targetRepository.create(
+      constrainDataObject(targetModelData, this.constraint),
+      options,
+    );
+  }
+
+  async get(
+    filter?: Pick<
+      Filter<TargetEntity>,
+      Exclude<keyof Filter<TargetEntity>, 'where'>
+    >,
+    options?: Options,
+  ): Promise<TargetEntity> {
+    const targetRepository = await this.getTargetRepository();
+    const found = await targetRepository.find(
+      Object.assign({limit: 1}, constrainFilter(filter, this.constraint)),
+      options,
+    );
+    if (found.length < 1) {
+      // We don't have a direct access to the foreign key value here :(
+      const id = 'constraint ' + JSON.stringify(this.constraint);
+      throw new EntityNotFoundError(targetRepository.entityClass, id);
+    }
+    return found[0];
+  }
+  async delete(options?: Options): Promise<Count> {
+    const targetRepository = await this.getTargetRepository();
+    return targetRepository.deleteAll(
+      constrainWhere({}, this.constraint),
+      options,
+    );
+  }
+
+  async patch(
+    dataObject: DataObject<TargetEntity>,
+    options?: Options,
+  ): Promise<Count> {
+    const targetRepository = await this.getTargetRepository();
+    return targetRepository.updateAll(
+      constrainDataObject(dataObject, this.constraint),
+      constrainWhere({}, this.constraint),
+      options,
+    );
+  }
+}

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

@@ -0,0 +1,8 @@
+// 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 './has-one.decorator';
+export * from './has-one.repository';
+export * from './has-one.repository-factory';

package/src/relations/index.ts

@@ -0,0 +1,11 @@
+// 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';
+export * from './has-many';
+export * from './has-one';
+export * from './relation.decorator';
+export * from './relation.helpers';
+export * from './relation.types';