@loopback/repository 4.0.0-alpha.9 → 4.0.0

package/src/decorators/model.decorator.ts

@@ -0,0 +1,166 @@
+// 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 {
+  ClassDecoratorFactory,
+  MetadataAccessor,
+  MetadataInspector,
+  MetadataMap,
+  PropertyDecoratorFactory,
+} from '@loopback/core';
+import {
+  ModelDefinition,
+  ModelDefinitionSyntax,
+  PropertyDefinition,
+  PropertyType,
+  RelationDefinitionMap,
+} from '../model';
+import {RELATIONS_KEY} from '../relations/relation.decorator';
+
+export const MODEL_KEY = MetadataAccessor.create<
+  Partial<ModelDefinitionSyntax>,
+  ClassDecorator
+>('loopback:model');
+export const MODEL_PROPERTIES_KEY = MetadataAccessor.create<
+  PropertyDefinition,
+  PropertyDecorator
+>('loopback:model-properties');
+export const MODEL_WITH_PROPERTIES_KEY = MetadataAccessor.create<
+  ModelDefinition,
+  ClassDecorator
+>('loopback:model-and-properties');
+
+export type PropertyMap = MetadataMap<Partial<PropertyDefinition>>;
+
+/**
+ * Decorator for model definitions
+ * @param definition
+ * @returns A class decorator for `model`
+ */
+export function model(definition?: Partial<ModelDefinitionSyntax>) {
+  return function (target: Function & {definition?: ModelDefinition}) {
+    definition = definition ?? {};
+    const def: ModelDefinitionSyntax = Object.assign(definition, {
+      name: definition.name ?? target.name,
+    });
+    const decorator = ClassDecoratorFactory.createDecorator(
+      MODEL_KEY,
+      definition,
+      {decoratorName: '@model'},
+    );
+
+    decorator(target);
+
+    // Build "ModelDefinition" and store it on model constructor
+    buildModelDefinition(target, def);
+  };
+}
+
+/**
+ * Build model definition from decorations
+ * @param target - Target model class
+ * @param def - Model definition spec
+ */
+export function buildModelDefinition(
+  target: Function & {definition?: ModelDefinition | undefined},
+  def?: ModelDefinitionSyntax,
+) {
+  // Check if the definition for this class has been built (not from the super
+  // class)
+  const baseClass = Object.getPrototypeOf(target);
+  if (
+    !def &&
+    target.definition &&
+    baseClass &&
+    target.definition !== baseClass.definition
+  ) {
+    return target.definition;
+  }
+  const modelDef = new ModelDefinition(def ?? {name: target.name});
+  const prototype = target.prototype;
+  const propertyMap: PropertyMap =
+    MetadataInspector.getAllPropertyMetadata(MODEL_PROPERTIES_KEY, prototype) ??
+    {};
+  for (const [propName, propDef] of Object.entries(propertyMap)) {
+    const designType =
+      propDef.type ??
+      MetadataInspector.getDesignTypeForProperty(prototype, propName);
+    if (!designType) {
+      const err: Error & {code?: string} = new Error(
+        `The definition of model property ${modelDef.name}.${propName} is missing ` +
+          '`type` field and TypeScript did not provide any design-time type. ' +
+          'Learn more at https://loopback.io/doc/en/lb4/Error-codes.html#cannot_infer_property_type',
+      );
+      err.code = 'CANNOT_INFER_PROPERTY_TYPE';
+      throw err;
+    }
+
+    if (propDef.hidden) {
+      modelDef.settings.hiddenProperties =
+        modelDef.settings.hiddenProperties ?? [];
+      modelDef.settings.hiddenProperties.push(propName);
+    }
+    propDef.type = designType;
+    modelDef.addProperty(propName, propDef);
+  }
+  target.definition = modelDef;
+  const relationMeta: RelationDefinitionMap =
+    MetadataInspector.getAllPropertyMetadata(RELATIONS_KEY, prototype) ?? {};
+  const relations: RelationDefinitionMap = {};
+  // Build an object keyed by relation names
+  Object.values(relationMeta).forEach(r => {
+    relations[r.name] = r;
+  });
+  target.definition.relations = relations;
+  return modelDef;
+}
+
+/**
+ * Decorator for model properties
+ * @param definition
+ * @returns A property decorator
+ */
+export function property(definition?: Partial<PropertyDefinition>) {
+  return PropertyDecoratorFactory.createDecorator(
+    MODEL_PROPERTIES_KEY,
+    Object.assign({}, definition),
+    {decoratorName: '@property'},
+  );
+}
+
+export namespace property {
+  export const ERR_PROP_NOT_ARRAY =
+    '@property.array can only decorate array properties!';
+  export const ERR_NO_ARGS = 'decorator received less than two parameters';
+
+  /**
+   *
+   * @param itemType - The type of array items.
+   * Examples: `number`, `Product`, `() => Order`.
+   * @param definition - Optional PropertyDefinition object for additional
+   * metadata
+   */
+  export function array(
+    itemType: PropertyType,
+    definition?: Partial<PropertyDefinition>,
+  ) {
+    return function (target: object, propertyName: string) {
+      const propType = MetadataInspector.getDesignTypeForProperty(
+        target,
+        propertyName,
+      );
+      if (propType !== Array) {
+        throw new Error(ERR_PROP_NOT_ARRAY);
+      } else {
+        property(
+          Object.assign(
+            {type: Array, itemType} as Partial<PropertyDefinition>,
+            definition,
+          ),
+        )(target, propertyName);
+      }
+    };
+  }
+}

package/src/decorators/repository.decorator.ts

@@ -0,0 +1,223 @@
+// 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 {Context, inject, Injection} from '@loopback/core';
+import assert from 'assert';
+import {Class} from '../common-types';
+import {DataSource} from '../datasource';
+import {Entity, Model} from '../model';
+import {DefaultCrudRepository, Repository} from '../repositories';
+import {juggler} from '../repositories/legacy-juggler-bridge';
+
+/**
+ * Type definition for decorators returned by `@repository` decorator factory
+ */
+export type RepositoryDecorator = (
+  target: Object,
+  key?: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  descriptorOrIndex?: TypedPropertyDescriptor<any> | number,
+) => void;
+
+/**
+ * Metadata for a repository
+ */
+export class RepositoryMetadata {
+  /**
+   * Name of the predefined repository
+   */
+  name?: string;
+  /**
+   * Name of the model
+   */
+  modelName?: string;
+  /**
+   * Class of the model
+   */
+  modelClass?: typeof Entity;
+  /**
+   * Name of the data source
+   */
+  dataSourceName?: string;
+  /**
+   * Instance of the data source
+   */
+  dataSource?: juggler.DataSource | DataSource;
+
+  /**
+   * Constructor for RepositoryMetadata
+   *
+   * @param modelOrRepo - Name or class of the model. If the value is a string and
+   * `dataSource` is not present, it will treated as the name of a predefined
+   * repository
+   * @param dataSource - Name or instance of the data source
+   *
+   * For example:
+   *
+   * - new RepositoryMetadata(repoName);
+   * - new RepositoryMetadata(modelName, dataSourceName);
+   * - new RepositoryMetadata(modelClass, dataSourceInstance);
+   * - new RepositoryMetadata(modelName, dataSourceInstance);
+   * - new RepositoryMetadata(modelClass, dataSourceName);
+   */
+  constructor(
+    modelOrRepo: string | typeof Entity,
+    dataSource?: string | juggler.DataSource | DataSource,
+  ) {
+    this.name =
+      typeof modelOrRepo === 'string' && dataSource === undefined
+        ? modelOrRepo
+        : undefined;
+    this.modelName =
+      typeof modelOrRepo === 'string' && dataSource != null
+        ? modelOrRepo
+        : undefined;
+    this.modelClass =
+      typeof modelOrRepo === 'function' ? modelOrRepo : undefined;
+    this.dataSourceName =
+      typeof dataSource === 'string' ? dataSource : undefined;
+    this.dataSource = typeof dataSource === 'object' ? dataSource : undefined;
+  }
+}
+
+/**
+ * Decorator for repository injections on properties or method arguments
+ *
+ * @example
+ * ```ts
+ * class CustomerController {
+ *   @repository(CustomerRepository) public custRepo: CustomerRepository;
+ *
+ *   constructor(
+ *     @repository(ProductRepository) public prodRepo: ProductRepository,
+ *   ) {}
+ *   // ...
+ * }
+ * ```
+ *
+ * @param repositoryName - Name of the repo
+ */
+export function repository(
+  repositoryName: string | Class<Repository<Model>>,
+): RepositoryDecorator;
+
+/**
+ * Decorator for DefaultCrudRepository generation and injection on properties
+ * or method arguments based on the given model and dataSource (or their names)
+ *
+ * @example
+ * ```ts
+ * class CustomerController {
+ *   @repository('Customer', 'mySqlDataSource')
+ *   public custRepo: DefaultCrudRepository<
+ *     Customer,
+ *     typeof Customer.prototype.id
+ *   >;
+ *
+ *   constructor(
+ *     @repository(Product, mySqlDataSource)
+ *     public prodRepo: DefaultCrudRepository<
+ *       Product,
+ *       typeof Product.prototype.id
+ *     >,
+ *   ) {}
+ *   // ...
+ * }
+ * ```
+ *
+ * @param model - Name/class of the model
+ * @param dataSource - Name/instance of the dataSource
+ */
+export function repository(
+  model: string | typeof Entity,
+  dataSource: string | juggler.DataSource,
+): RepositoryDecorator;
+
+export function repository(
+  modelOrRepo: string | Class<Repository<Model>> | typeof Entity,
+  dataSource?: string | juggler.DataSource,
+) {
+  // if string, repository or not a model ctor,
+  // keep it a string / assign to ctor's name (string) for DI
+  const stringOrModel =
+    typeof modelOrRepo !== 'string' && !modelOrRepo.prototype.getId
+      ? modelOrRepo.name
+      : (modelOrRepo as typeof Entity);
+  const meta = new RepositoryMetadata(stringOrModel, dataSource);
+  return function (
+    target: Object,
+    key?: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    descriptorOrIndex?: TypedPropertyDescriptor<any> | number,
+  ) {
+    if (key || typeof descriptorOrIndex === 'number') {
+      if (meta.name) {
+        // Make it shortcut to `@inject('repositories.MyRepo')`
+        // Please note key is undefined for constructor. If strictNullChecks
+        // is true, the compiler will complain as reflect-metadata won't
+        // accept undefined or null for key. Use ! to fool the compiler.
+        inject('repositories.' + meta.name, meta)(
+          target,
+          key!,
+          descriptorOrIndex,
+        );
+      } else {
+        // Use repository-factory to create a repository from model + dataSource
+        inject('', meta, resolve)(target, key!, descriptorOrIndex);
+      }
+      return;
+    }
+    // Mixin repository into the class
+    throw new Error('Class level @repository is not implemented');
+  };
+}
+
+export namespace repository {
+  /**
+   * Decorator used to inject a Getter for a repository
+   * Mainly intended for usage with repository injections on relation repository
+   * factory
+   * @param nameOrClass - The repository class (ProductRepository) or a string name ('ProductRepository').
+   */
+  export function getter(nameOrClass: string | Class<Repository<Model>>) {
+    const name =
+      typeof nameOrClass === 'string' ? nameOrClass : nameOrClass.name;
+    return inject.getter(`repositories.${name}`);
+  }
+}
+
+/**
+ * Resolve the @repository injection
+ * @param ctx - Context
+ * @param injection - Injection metadata
+ */
+async function resolve(ctx: Context, injection: Injection) {
+  const meta = injection.metadata as RepositoryMetadata;
+  let modelClass = meta.modelClass;
+  if (meta.modelName) {
+    modelClass = (await ctx.get('models.' + meta.modelName)) as typeof Entity;
+  }
+  if (!modelClass) {
+    throw new Error(
+      'Invalid repository config: ' +
+        ' neither modelClass nor modelName was specified.',
+    );
+  }
+
+  let dataSource = meta.dataSource;
+  if (meta.dataSourceName) {
+    dataSource = await ctx.get<DataSource>(
+      'datasources.' + meta.dataSourceName,
+    );
+  }
+  assert(
+    dataSource instanceof juggler.DataSource,
+    'DataSource must be provided',
+  );
+  return new DefaultCrudRepository(
+    modelClass,
+    dataSource! as juggler.DataSource,
+  );
+}

package/src/define-model-class.ts

@@ -0,0 +1,90 @@
+// 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 * as assert from 'assert';
+import {DataObject, PrototypeOf} from './common-types';
+import {model} from './decorators';
+import {Model, ModelDefinition} from './model';
+
+/**
+ * Create (define) a new model class with the given name and definition.
+ *
+ * @remarks
+ *
+ * ```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.
+ * @typeParam BaseCtor Constructor type of the base class,
+ *   e.g `typeof Model` or `typeof Entity`
+ * @typeParam 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);
+
+  // Apply `@model(definition)` to the generated class
+  model(definition)(modelClass);
+  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,
+> = {
+  /** Model constructor accepting partial model data. */
+  new (
+    data?: DataObject<PrototypeOf<BaseCtor> & Props>,
+  ): PrototypeOf<BaseCtor> & Props;
+} & BaseCtor;

package/src/define-repository-class.ts

@@ -0,0 +1,170 @@
+// 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 assert from 'assert';
+import {PrototypeOf} from './common-types';
+import {Entity, Model} from './model';
+import {
+  DefaultCrudRepository,
+  DefaultKeyValueRepository,
+  juggler,
+  Repository,
+} from './repositories';
+
+/**
+ * Signature for a Repository class bound to a given model. The constructor
+ * accepts only the dataSource to use for persistence.
+ *
+ * `define*` functions return a class implementing this interface.
+ *
+ * @typeParam M - Model class
+ * @typeParam R - Repository class/interface
+ */
+export interface ModelRepositoryClass<
+  M extends Model,
+  R extends Repository<M>,
+> {
+  /**
+   * The constructor for the generated repository class
+   * @param dataSource - DataSource object
+   */
+  new (dataSource: juggler.DataSource): R;
+  prototype: R;
+}
+
+/**
+ * Signature for repository classes that can be used as the base class for
+ * `define*` functions. The constructor of a base repository class accepts
+ * the target model constructor and the datasource to use.
+ *
+ * `define*` functions require a class implementing this interface on input.
+ *
+ * @typeParam M - Model class constructor, e.g `typeof Model`.
+ * **❗️IMPORTANT: The type argument `M` is describing the model constructor type
+ * (e.g. `typeof Model`), not the model instance type (`Model`) as is the case
+ * in other repository-related types. The constructor type is required
+ * to support custom repository classes requiring a Model subclass in the
+ * constructor arguments, e.g. `Entity` or a user-provided model.**
+ *
+ * @typeParam R - Repository class/interface
+ */
+export interface BaseRepositoryClass<
+  M extends typeof Model,
+  R extends Repository<PrototypeOf<M>>,
+> {
+  /**
+   * The constructor for the generated repository class
+   * @param modelClass - Model class
+   * @param dataSource - DataSource object
+   */
+  new (modelClass: M, dataSource: juggler.DataSource): R;
+  prototype: R;
+}
+
+/**
+ * Create (define) a repository class for the given model.
+ *
+ * See also `defineCrudRepositoryClass` and `defineKeyValueRepositoryClass`
+ * for convenience wrappers providing repository class factory for the default
+ * CRUD and KeyValue implementations.
+ *
+ * **❗️IMPORTANT: The compiler (TypeScript 3.8) is not able to correctly infer
+ * generic arguments `M` and `R` from the class constructors provided in
+ * function arguments. You must always provide both M and R types explicitly.**
+ *
+ * @example
+ *
+ * ```ts
+ * const AddressRepository = defineRepositoryClass<
+ *   typeof Address,
+ *   DefaultEntityCrudRepository<
+ *    Address,
+ *    typeof Address.prototype.id,
+ *    AddressRelations
+ *   >,
+ * >(Address, DefaultCrudRepository);
+ * ```
+ *
+ * @param modelClass - A model class such as `Address`.
+ * @param baseRepositoryClass - Repository implementation to use as the base,
+ * e.g. `DefaultCrudRepository`.
+ *
+ * @typeParam M - Model class constructor (e.g. `typeof Address`)
+ * @typeParam R - Repository class (e.g. `DefaultCrudRepository<Address, number>`)
+ */
+export function defineRepositoryClass<
+  M extends typeof Model,
+  R extends Repository<PrototypeOf<M>>,
+>(
+  modelClass: M,
+  baseRepositoryClass: BaseRepositoryClass<M, R>,
+): ModelRepositoryClass<PrototypeOf<M>, R> {
+  const repoName = modelClass.name + 'Repository';
+  const defineNamedRepo = new Function(
+    'ModelCtor',
+    'BaseRepository',
+    `return class ${repoName} extends BaseRepository {
+      constructor(dataSource) {
+        super(ModelCtor, dataSource);
+      }
+    };`,
+  );
+
+  const repo = defineNamedRepo(modelClass, baseRepositoryClass);
+  assert.equal(repo.name, repoName);
+  return repo;
+}
+
+/**
+ * Create (define) an entity CRUD repository class for the given model.
+ * This function always uses `DefaultCrudRepository` as the base class,
+ * use `defineRepositoryClass` if you want to use your own base repository.
+ *
+ * @example
+ *
+ * ```ts
+ * const ProductRepository = defineCrudRepositoryClass<
+ *   Product,
+ *   typeof Product.prototype.id,
+ *   ProductRelations
+ * >(Product);
+ * ```
+ *
+ * @param entityClass - An entity class such as `Product`.
+ *
+ * @typeParam E - An entity class
+ * @typeParam IdType - ID type for the entity
+ * @typeParam Relations - Relations for the entity
+ */
+export function defineCrudRepositoryClass<
+  E extends Entity,
+  IdType,
+  Relations extends object,
+>(
+  entityClass: typeof Entity & {prototype: E},
+): ModelRepositoryClass<E, DefaultCrudRepository<E, IdType, Relations>> {
+  return defineRepositoryClass(entityClass, DefaultCrudRepository);
+}
+
+/**
+ * Create (define) a KeyValue repository class for the given entity.
+ * This function always uses `DefaultKeyValueRepository` as the base class,
+ * use `defineRepositoryClass` if you want to use your own base repository.
+ *
+ * @example
+ *
+ * ```ts
+ * const ProductKeyValueRepository = defineKeyValueRepositoryClass(Product);
+ * ```
+ *
+ * @param modelClass - An entity class such as `Product`.
+ *
+ * @typeParam M - Model class
+ */
+export function defineKeyValueRepositoryClass<M extends Model>(
+  modelClass: typeof Model & {prototype: M},
+): ModelRepositoryClass<M, DefaultKeyValueRepository<M>> {
+  return defineRepositoryClass(modelClass, DefaultKeyValueRepository);
+}

package/src/errors/entity-not-found.error.ts

@@ -0,0 +1,40 @@
+// Copyright IBM Corp. 2018,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 {Entity} from '../model';
+
+export class EntityNotFoundError<ID, Props extends object = {}> extends Error {
+  code: string;
+  entityName: string;
+  entityId: ID;
+
+  constructor(
+    entityOrName: typeof Entity | string,
+    entityId: ID,
+    extraProperties?: Props,
+  ) {
+    const entityName =
+      typeof entityOrName === 'string'
+        ? entityOrName
+        : entityOrName.modelName || entityOrName.name;
+
+    const quotedId = JSON.stringify(entityId);
+
+    super(`Entity not found: ${entityName} with id ${quotedId}`);
+
+    Error.captureStackTrace(this, this.constructor);
+
+    this.code = 'ENTITY_NOT_FOUND';
+    this.entityName = entityName;
+    this.entityId = entityId;
+
+    Object.assign(this, extraProperties);
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function isEntityNotFoundError(e: any): e is EntityNotFoundError<any> {
+  return e instanceof EntityNotFoundError;
+}

package/src/errors/index.ts

@@ -0,0 +1,7 @@
+// Copyright IBM Corp. 2018. 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 './entity-not-found.error';
+export * from './invalid-relation.error';