@loopback/repository 4.0.0-alpha.9 → 4.0.0

package/src/model.ts

@@ -0,0 +1,539 @@
+// Copyright IBM Corp. 2017,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 {AnyObject, DataObject, Options, PrototypeOf} from './common-types';
+import {
+  BelongsToDefinition,
+  HasManyDefinition,
+  HasOneDefinition,
+  JsonSchema,
+  RelationMetadata,
+  RelationType,
+} from './index';
+import {TypeResolver} from './type-resolver';
+import {Type} from './types';
+
+/**
+ * This module defines the key classes representing building blocks for Domain
+ * Driven Design.
+ * See https://en.wikipedia.org/wiki/Domain-driven_design#Building_blocks
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+export interface JsonSchemaWithExtensions extends JsonSchema {
+  [attributes: string]: any;
+}
+
+export type PropertyType =
+  | string
+  | Function
+  | object
+  | Type<any>
+  | TypeResolver<Model>;
+
+/**
+ * Property definition for a model
+ */
+export interface PropertyDefinition {
+  type: PropertyType; // For example, 'string', String, or {}
+  id?: boolean | number;
+  /**
+   * Used to hide this property from the response body,
+   * adding this property to the hiddenProperties array
+   */
+  hidden?: boolean;
+  json?: PropertyForm;
+  jsonSchema?: JsonSchemaWithExtensions;
+  store?: PropertyForm;
+  itemType?: PropertyType; // type of array
+  [attribute: string]: any; // Other attributes
+}
+
+/**
+ * Defining the settings for a model
+ * See https://loopback.io/doc/en/lb4/Model.html#supported-entries-of-model-definition
+ */
+export interface ModelSettings {
+  /**
+   * Description of the model
+   */
+  description?: string;
+  /**
+   * Prevent clients from setting the auto-generated ID value manually
+   */
+  forceId?: boolean;
+  /**
+   * Hides properties from response bodies
+   */
+  hiddenProperties?: string[];
+  /**
+   * Scope enables you to set a scope that will apply to every query made by the model's repository
+   */
+  scope?: object;
+  /**
+   * Specifies whether the model accepts only predefined properties or not
+   */
+  strict?: boolean | 'filter';
+
+  // Other variable settings
+  [name: string]: any;
+}
+
+/**
+ * See https://github.com/loopbackio/loopback-datasource-juggler/issues/432
+ */
+export interface PropertyForm {
+  in?: boolean; // Can the property be used for input
+  out?: boolean; // Can the property be used for output
+  name?: string; // Custom name for this form
+}
+
+/**
+ * A key-value map describing model relations.
+ * A relation name is used as the key, a relation definition is the value.
+ */
+export type RelationDefinitionMap = {
+  [relationName: string]: RelationMetadata;
+};
+
+/**
+ * DSL for building a model definition.
+ */
+export interface ModelDefinitionSyntax {
+  name: string;
+  properties?: {[name: string]: PropertyDefinition | PropertyType};
+  settings?: ModelSettings;
+  relations?: RelationDefinitionMap;
+  jsonSchema?: JsonSchemaWithExtensions;
+  [attribute: string]: any;
+}
+
+/**
+ * Definition for a model
+ */
+export class ModelDefinition {
+  readonly name: string;
+  properties: {[name: string]: PropertyDefinition};
+  settings: ModelSettings;
+  relations: RelationDefinitionMap;
+  // indexes: Map<string, any>;
+  [attribute: string]: any; // Other attributes
+
+  constructor(nameOrDef: string | ModelDefinitionSyntax) {
+    if (typeof nameOrDef === 'string') {
+      nameOrDef = {name: nameOrDef};
+    }
+    const {name, properties, settings, relations} = nameOrDef;
+
+    this.name = name;
+
+    this.properties = {};
+    if (properties) {
+      for (const p in properties) {
+        this.addProperty(p, properties[p]);
+      }
+    }
+
+    this.settings = settings ?? new Map();
+    this.relations = relations ?? {};
+  }
+
+  /**
+   * Add a property
+   * @param name - Property definition or name (string)
+   * @param definitionOrType - Definition or property type
+   */
+  addProperty(
+    name: string,
+    definitionOrType: PropertyDefinition | PropertyType,
+  ): this {
+    const definition = (definitionOrType as PropertyDefinition).type
+      ? (definitionOrType as PropertyDefinition)
+      : {type: definitionOrType};
+
+    if (
+      definition.id === true &&
+      definition.generated === true &&
+      definition.type !== undefined &&
+      definition.useDefaultIdType === undefined
+    ) {
+      definition.useDefaultIdType = false;
+    }
+
+    this.properties[name] = definition;
+    return this;
+  }
+
+  /**
+   * Add a setting
+   * @param name - Setting name
+   * @param value - Setting value
+   */
+  addSetting(name: string, value: any): this {
+    this.settings[name] = value;
+    return this;
+  }
+
+  /**
+   * Define a new relation.
+   * @param definition - The definition of the new relation.
+   */
+  addRelation(definition: RelationMetadata): this {
+    this.relations[definition.name] = definition;
+    return this;
+  }
+
+  /**
+   * Define a new belongsTo relation.
+   * @param name - The name of the belongsTo relation.
+   * @param definition - The definition of the belongsTo relation.
+   */
+  belongsTo(
+    name: string,
+    definition: Omit<BelongsToDefinition, 'name' | 'type' | 'targetsMany'>,
+  ): this {
+    const meta: BelongsToDefinition = {
+      ...definition,
+      name,
+      type: RelationType.belongsTo,
+      targetsMany: false,
+    };
+    return this.addRelation(meta);
+  }
+
+  /**
+   * Define a new hasOne relation.
+   * @param name - The name of the hasOne relation.
+   * @param definition - The definition of the hasOne relation.
+   */
+  hasOne(
+    name: string,
+    definition: Omit<HasOneDefinition, 'name' | 'type' | 'targetsMany'>,
+  ): this {
+    const meta: HasOneDefinition = {
+      ...definition,
+      name,
+      type: RelationType.hasOne,
+      targetsMany: false,
+    };
+    return this.addRelation(meta);
+  }
+
+  /**
+   * Define a new hasMany relation.
+   * @param name - The name of the hasMany relation.
+   * @param definition - The definition of the hasMany relation.
+   */
+  hasMany(
+    name: string,
+    definition: Omit<HasManyDefinition, 'name' | 'type' | 'targetsMany'>,
+  ): this {
+    const meta: HasManyDefinition = {
+      ...definition,
+      name,
+      type: RelationType.hasMany,
+      targetsMany: true,
+    };
+    return this.addRelation(meta);
+  }
+
+  /**
+   * Get an array of names of ID properties, which are specified in
+   * the model settings or properties with `id` attribute.
+   *
+   * @example
+   * ```ts
+   * {
+   *   settings: {
+   *     id: ['id']
+   *   }
+   *   properties: {
+   *     id: {
+   *       type: 'string',
+   *       id: true
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  idProperties(): string[] {
+    if (typeof this.settings.id === 'string') {
+      return [this.settings.id];
+    } else if (Array.isArray(this.settings.id)) {
+      return this.settings.id;
+    }
+    const idProps = Object.keys(this.properties).filter(
+      prop => this.properties[prop].id,
+    );
+    return idProps;
+  }
+}
+
+function asJSON(value: any): any {
+  if (value == null) return value;
+  if (typeof value.toJSON === 'function') {
+    return value.toJSON();
+  }
+  // Handle arrays
+  if (Array.isArray(value)) {
+    return value.map(item => asJSON(item));
+  }
+  return value;
+}
+
+/**
+ * Convert a value to a plain object as DTO.
+ *
+ * - The prototype of the value in primitive types are preserved,
+ *   like `Date`, `ObjectId`.
+ * - If the value is an instance of custom model, call `toObject` to convert.
+ * - If the value is an array, convert each element recursively.
+ *
+ * @param value the value to convert
+ * @param options the options
+ */
+function asObject(value: any, options?: Options): any {
+  if (value == null) return value;
+  if (typeof value.toObject === 'function') {
+    return value.toObject(options);
+  }
+  if (Array.isArray(value)) {
+    return value.map(item => asObject(item, options));
+  }
+  return value;
+}
+
+/**
+ * Base class for models
+ */
+export class Model {
+  static get modelName(): string {
+    return this.definition?.name || this.name;
+  }
+
+  static definition: ModelDefinition;
+
+  /**
+   * Serialize into a plain JSON object
+   */
+  toJSON(): Object {
+    const def = (this.constructor as typeof Model).definition;
+    if (def == null || def.settings.strict === false) {
+      return this.toObject({ignoreUnknownProperties: false});
+    }
+
+    const copyPropertyAsJson = (key: string) => {
+      const val = asJSON((this as AnyObject)[key]);
+      if (val !== undefined) {
+        json[key] = val;
+      }
+    };
+
+    const json: AnyObject = {};
+    const hiddenProperties: string[] = def.settings.hiddenProperties || [];
+    for (const p in def.properties) {
+      if (p in this && !hiddenProperties.includes(p)) {
+        copyPropertyAsJson(p);
+      }
+    }
+
+    for (const r in def.relations) {
+      const relName = def.relations[r].name;
+      if (relName in this) {
+        copyPropertyAsJson(relName);
+      }
+    }
+
+    return json;
+  }
+
+  /**
+   * Convert to a plain object as DTO
+   *
+   * If `ignoreUnknownProperty` is set to false, convert all properties in the
+   * model instance, otherwise only convert the ones defined in the model
+   * definitions.
+   *
+   * See function `asObject` for each property's conversion rules.
+   */
+  toObject(options?: Options): Object {
+    const def = (this.constructor as typeof Model).definition;
+    const obj: AnyObject = {};
+
+    if (options?.ignoreUnknownProperties === false) {
+      const hiddenProperties: string[] = def?.settings.hiddenProperties || [];
+      for (const p in this) {
+        if (!hiddenProperties.includes(p)) {
+          const val = (this as AnyObject)[p];
+          obj[p] = asObject(val, options);
+        }
+      }
+      return obj;
+    }
+
+    if (def?.relations) {
+      for (const r in def.relations) {
+        const relName = def.relations[r].name;
+        if (relName in this) {
+          obj[relName] = asObject((this as AnyObject)[relName], {
+            ...options,
+            ignoreUnknownProperties: false,
+          });
+        }
+      }
+    }
+
+    const props = def.properties;
+    const keys = Object.keys(props);
+
+    for (const i in keys) {
+      const propertyName = keys[i];
+      const val = (this as AnyObject)[propertyName];
+
+      if (val === undefined) continue;
+      obj[propertyName] = asObject(val, options);
+    }
+
+    return obj;
+  }
+
+  constructor(data?: DataObject<Model>) {
+    Object.assign(this, data);
+  }
+}
+
+export interface Persistable {
+  // isNew: boolean;
+}
+
+/**
+ * Base class for value objects - An object that contains attributes but has no
+ * conceptual identity. They should be treated as immutable.
+ */
+export abstract class ValueObject extends Model implements Persistable {}
+
+/**
+ * Base class for entities which have unique ids
+ */
+export class Entity extends Model implements Persistable {
+  /**
+   * Get the names of identity properties (primary keys).
+   */
+  static getIdProperties(): string[] {
+    return this.definition.idProperties();
+  }
+
+  /**
+   * Get the identity value for a given entity instance or entity data object.
+   *
+   * @param entityOrData - The data object for which to determine the identity
+   * value.
+   */
+  static getIdOf(entityOrData: AnyObject): any {
+    if (typeof entityOrData.getId === 'function') {
+      return entityOrData.getId();
+    }
+
+    const idName = this.getIdProperties()[0];
+    return entityOrData[idName];
+  }
+
+  /**
+   * Get the identity value. If the identity is a composite key, returns
+   * an object.
+   */
+  getId(): any {
+    const definition = (this.constructor as typeof Entity).definition;
+    const idProps = definition.idProperties();
+    if (idProps.length === 1) {
+      return (this as AnyObject)[idProps[0]];
+    }
+    if (!idProps.length) {
+      throw new Error(
+        `Invalid Entity ${this.constructor.name}:` +
+          'missing primary key (id) property',
+      );
+    }
+    return this.getIdObject();
+  }
+
+  /**
+   * Get the identity as an object, such as `{id: 1}` or
+   * `{schoolId: 1, studentId: 2}`
+   */
+  getIdObject(): Object {
+    const definition = (this.constructor as typeof Entity).definition;
+    const idProps = definition.idProperties();
+    const idObj = {} as any;
+    for (const idProp of idProps) {
+      idObj[idProp] = (this as AnyObject)[idProp];
+    }
+    return idObj;
+  }
+
+  /**
+   * Build the where object for the given id
+   * @param id - The id value
+   */
+  static buildWhereForId(id: any) {
+    const where = {} as any;
+    const idProps = this.definition.idProperties();
+    if (idProps.length === 1) {
+      where[idProps[0]] = id;
+    } else {
+      for (const idProp of idProps) {
+        where[idProp] = id[idProp];
+      }
+    }
+    return where;
+  }
+}
+
+/**
+ * Domain events
+ */
+export class Event {
+  source: any;
+  type: string;
+}
+
+export type EntityData = DataObject<Entity>;
+
+export type EntityResolver<T extends Entity> = TypeResolver<T, typeof Entity>;
+
+/**
+ * Check model data for navigational properties linking to related models.
+ * Throw a descriptive error if any such property is found.
+ *
+ * @param modelClass Model constructor, e.g. `Product`.
+ * @param entityData  Model instance or a plain-data object,
+ * e.g. `{name: 'pen'}`.
+ */
+export function rejectNavigationalPropertiesInData<M extends typeof Entity>(
+  modelClass: M,
+  data: DataObject<PrototypeOf<M>>,
+) {
+  const def = modelClass.definition;
+  const props = def.properties;
+
+  for (const r in def.relations) {
+    const relName = def.relations[r].name;
+    if (!(relName in data)) continue;
+
+    let msg =
+      'Navigational properties are not allowed in model data ' +
+      `(model "${modelClass.modelName}" property "${relName}"), ` +
+      'please remove it.';
+
+    if (relName in props) {
+      msg +=
+        ' The error might be invoked by belongsTo relations, please make' +
+        ' sure the relation name is not the same as the property name.';
+    }
+
+    throw new Error(msg);
+  }
+}

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

@@ -0,0 +1,74 @@
+// 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 debugFactory from 'debug';
+import {DataObject} from '../../common-types';
+import {Entity} from '../../model';
+import {EntityCrudRepository} from '../../repositories/repository';
+import {
+  BelongsToDefinition,
+  Getter,
+  InclusionResolver,
+} from '../relation.types';
+import {resolveBelongsToMetadata} from './belongs-to.helpers';
+import {createBelongsToInclusionResolver} from './belongs-to.inclusion-resolver';
+import {DefaultBelongsToRepository} from './belongs-to.repository';
+
+const debug = debugFactory('loopback:repository:relations:belongs-to:accessor');
+
+export interface BelongsToAccessor<Target extends Entity, SourceId> {
+  /**
+   * Invoke the function to obtain HasManyRepository.
+   */
+  (sourceId: SourceId): Promise<Target>;
+
+  /**
+   * Use `resolver` property to obtain an InclusionResolver for this relation.
+   */
+  inclusionResolver: InclusionResolver<Entity, Target>;
+}
+
+/**
+ * Enforces a BelongsTo constraint on a repository
+ */
+export function createBelongsToAccessor<
+  Target extends Entity,
+  TargetId,
+  Source extends Entity,
+  SourceId,
+>(
+  belongsToMetadata: BelongsToDefinition,
+  targetRepoGetter: Getter<EntityCrudRepository<Target, TargetId>>,
+  sourceRepository: EntityCrudRepository<Source, SourceId>,
+): BelongsToAccessor<Target, SourceId> {
+  const meta = resolveBelongsToMetadata(belongsToMetadata);
+  debug('Resolved BelongsTo relation metadata: %o', meta);
+  const result: BelongsToAccessor<Target, SourceId> =
+    async function getTargetInstanceOfBelongsTo(sourceId: SourceId) {
+      const foreignKey = meta.keyFrom;
+      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/loopbackio/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(
+        targetRepoGetter,
+        constraint as DataObject<Target>,
+      );
+      return constrainedRepo.get();
+    };
+
+  result.inclusionResolver = createBelongsToInclusionResolver(
+    meta,
+    targetRepoGetter,
+  );
+  return result;
+}

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

@@ -0,0 +1,81 @@
+// 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 {DecoratorFactory, MetadataInspector} from '@loopback/core';
+import {property} from '../../decorators';
+import {relation} from '../relation.decorator';
+import {Entity, EntityResolver, PropertyDefinition} from '../../model';
+import {BelongsToDefinition, RelationType} from '../relation.types';
+
+/**
+ * Decorator for belongsTo
+ * @param targetResolver - A resolver function that returns the target model for
+ * a belongsTo relation
+ * @param definition - Optional metadata for setting up a belongsTo relation
+ * @param propertyDefinition - Optional metadata for setting up the property
+ * @returns A property decorator
+ */
+export function belongsTo<T extends Entity>(
+  targetResolver: EntityResolver<T>,
+  definition?: Partial<BelongsToDefinition>,
+  propertyDefinition?: Partial<PropertyDefinition>,
+) {
+  return function (decoratedTarget: Entity, decoratedKey: string) {
+    const propType =
+      MetadataInspector.getDesignTypeForProperty(
+        decoratedTarget,
+        decoratedKey,
+      ) ?? propertyDefinition?.type;
+
+    if (!propType) {
+      const fullPropName = DecoratorFactory.getTargetName(
+        decoratedTarget,
+        decoratedKey,
+      );
+      throw new Error(
+        `Cannot infer type of model property ${fullPropName} because ` +
+          'TypeScript compiler option `emitDecoratorMetadata` is not set. ' +
+          'Please enable `emitDecoratorMetadata` or use the third argument of ' +
+          '`@belongsTo` decorator to specify the property type explicitly.',
+      );
+    }
+
+    const propMeta: PropertyDefinition = Object.assign(
+      {},
+      // properties provided by the caller
+      propertyDefinition,
+      // properties enforced by the decorator
+      {
+        type: propType,
+        // TODO(bajtos) Make the foreign key required once our REST API layer
+        // allows controller methods to exclude required properties
+        // required: true,
+      },
+    );
+    property(propMeta)(decoratedTarget, decoratedKey);
+
+    // @belongsTo() is typically decorating the foreign key property,
+    // e.g. customerId. We need to strip the trailing "Id" suffix from the name.
+    const relationName = decoratedKey.replace(/Id$/, '');
+
+    const meta: BelongsToDefinition = Object.assign(
+      // default values, can be customized by the caller
+      {
+        keyFrom: decoratedKey,
+        name: relationName,
+      },
+      // properties provided by the caller
+      definition,
+      // properties enforced by the decorator
+      {
+        type: RelationType.belongsTo,
+        targetsMany: false,
+        source: decoratedTarget.constructor,
+        target: targetResolver,
+      },
+    );
+    relation(meta)(decoratedTarget, decoratedKey);
+  };
+}