@loopback/repository 4.0.0-alpha.9 → 4.0.0

package/src/repositories/repository.ts

@@ -0,0 +1,441 @@
+// 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 {Filter, FilterExcludingWhere, Where} from '@loopback/filter';
+import {
+  AnyObject,
+  Command,
+  Count,
+  DataObject,
+  NamedParameters,
+  Options,
+  PositionalParameters,
+} from '../common-types';
+import {CrudConnector} from '../connectors';
+import {DataSource} from '../datasource';
+import {EntityNotFoundError} from '../errors';
+import {Entity, Model, ValueObject} from '../model';
+import {InclusionResolver} from '../relations/relation.types';
+import {IsolationLevel, Transaction} from '../transaction';
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+export interface Repository<T extends Model> {}
+
+export interface ExecutableRepository<T extends Model> extends Repository<T> {
+  /**
+   * Execute a query with the given parameter object or an array of parameters
+   * @param command - The query string or command object
+   * @param parameters - The object with name/value pairs or an array of parameter
+   * values
+   * @param options - Options
+   */
+  execute(
+    command: Command,
+    parameters: NamedParameters | PositionalParameters,
+    options?: Options,
+  ): Promise<AnyObject>;
+}
+
+/**
+ * A type for CRUD repositories that are backed by IDs and support
+ * Transactions
+ */
+export type TransactionalEntityRepository<
+  T extends Entity,
+  ID,
+  Relations extends object = {},
+> = TransactionalRepository<T> & EntityCrudRepository<T, ID>;
+/**
+ * Repository Interface for Repositories that support Transactions
+ *
+ * @typeParam T Generic type for the Entity
+ */
+export interface TransactionalRepository<T extends Entity>
+  extends Repository<T> {
+  /**
+   * Begin a new Transaction
+   * @param options - Options for the operations
+   * @returns Promise<Transaction> Promise that resolves to a new Transaction
+   * object
+   */
+  beginTransaction(options?: IsolationLevel | Options): Promise<Transaction>;
+}
+
+/**
+ * Basic CRUD operations for ValueObject and Entity. No ID is required.
+ */
+export interface CrudRepository<
+  T extends ValueObject | Entity,
+  Relations extends object = {},
+> extends Repository<T> {
+  /**
+   * Create a new record
+   * @param dataObject - The data to be created
+   * @param options - Options for the operations
+   * @returns A promise of record created
+   */
+  create(dataObject: DataObject<T>, options?: Options): Promise<T>;
+
+  /**
+   * Create all records
+   * @param dataObjects - An array of data to be created
+   * @param options - Options for the operations
+   * @returns A promise of an array of records created
+   */
+  createAll(dataObjects: DataObject<T>[], options?: Options): Promise<T[]>;
+
+  /**
+   * Find matching records
+   * @param filter - Query filter
+   * @param options - Options for the operations
+   * @returns A promise of an array of records found
+   */
+  find(filter?: Filter<T>, options?: Options): Promise<(T & Relations)[]>;
+
+  /**
+   * Updating matching records with attributes from the data object
+   * @param dataObject - The data to be updated
+   * @param where - Matching criteria
+   * @param options - Options for the operations
+   * @returns A promise of number of records updated
+   */
+  updateAll(
+    dataObject: DataObject<T>,
+    where?: Where<T>,
+    options?: Options,
+  ): Promise<Count>;
+
+  /**
+   * Delete matching records
+   * @param where - Matching criteria
+   * @param options - Options for the operations
+   * @returns A promise of number of records deleted
+   */
+  deleteAll(where?: Where<T>, options?: Options): Promise<Count>;
+
+  /**
+   * Count matching records
+   * @param where - Matching criteria
+   * @param options - Options for the operations
+   * @returns A promise of number of records matched
+   */
+  count(where?: Where<T>, options?: Options): Promise<Count>;
+}
+
+/**
+ * Base interface for a repository of entities
+ */
+export interface EntityRepository<T extends Entity, ID>
+  extends ExecutableRepository<T> {}
+
+/**
+ * CRUD operations for a repository of entities
+ */
+export interface EntityCrudRepository<
+  T extends Entity,
+  ID,
+  Relations extends object = {},
+> extends EntityRepository<T, ID>,
+    CrudRepository<T, Relations> {
+  // entityClass should have type "typeof T", but that's not supported by TSC
+  entityClass: typeof Entity & {prototype: T};
+  inclusionResolvers: Map<string, InclusionResolver<T, Entity>>;
+
+  /**
+   * Save an entity. If no id is present, create a new entity
+   * @param entity - Entity to be saved
+   * @param options - Options for the operations
+   * @returns A promise that will be resolve if the operation succeeded or will
+   * be rejected if the entity was not found.
+   */
+  save(entity: DataObject<T>, options?: Options): Promise<T>;
+
+  /**
+   * Update an entity
+   * @param entity - Entity to be updated
+   * @param options - Options for the operations
+   * @returns A promise that will be resolve if the operation succeeded or will
+   * be rejected if the entity was not found.
+   */
+  update(entity: DataObject<T>, options?: Options): Promise<void>;
+
+  /**
+   * Delete an entity
+   * @param entity - Entity to be deleted
+   * @param options - Options for the operations
+   * @returns A promise that will be resolve if the operation succeeded or will
+   * be rejected if the entity was not found.
+   */
+  delete(entity: DataObject<T>, options?: Options): Promise<void>;
+
+  /**
+   * Find an entity by id, return a rejected promise if not found.
+   *
+   * @remarks
+   *
+   * The rationale behind findById is to find an instance by its primary key
+   * (id). No other search criteria than id should be used. If a client wants
+   * to use a `where` clause beyond id, use `find` or `findOne` instead.
+   *
+   * @param id - Value for the entity id
+   * @param filter - Additional query options. E.g. `filter.include` configures
+   * which related models to fetch as part of the database query (or queries).
+   * @param options - Options for the operations
+   * @returns A promise of an entity found for the id
+   */
+  findById(
+    id: ID,
+    filter?: FilterExcludingWhere<T>,
+    options?: Options,
+  ): Promise<T & Relations>;
+
+  /**
+   * Update an entity by id with property/value pairs in the data object
+   * @param id - Value for the entity id
+   * @param data - Data attributes to be updated
+   * @param options - Options for the operations
+   * @returns A promise that will be resolve if the operation succeeded or will
+   * be rejected if the entity was not found.
+   */
+  updateById(id: ID, data: DataObject<T>, options?: Options): Promise<void>;
+
+  /**
+   * Replace an entity by id
+   * @param id - Value for the entity id
+   * @param data - Data attributes to be replaced
+   * @param options - Options for the operations
+   * @returns A promise that will be resolve if the operation succeeded or will
+   * be rejected if the entity was not found.
+   */
+  replaceById(id: ID, data: DataObject<T>, options?: Options): Promise<void>;
+
+  /**
+   * Delete an entity by id
+   * @param id - Value for the entity id
+   * @param options - Options for the operations
+   * @returns A promise that will be resolve if the operation succeeded or will
+   * be rejected if the entity was not found.
+   */
+  deleteById(id: ID, options?: Options): Promise<void>;
+
+  /**
+   * Check if an entity exists for the given id
+   * @param id - Value for the entity id
+   * @param options - Options for the operations
+   * @returns Promise<true> if an entity exists for the id, otherwise
+   * Promise<false>
+   */
+  exists(id: ID, options?: Options): Promise<boolean>;
+}
+
+/**
+ * Repository implementation
+ *
+ * @example
+ *
+ * User can import `CrudRepositoryImpl` and call its functions like:
+ * `CrudRepositoryImpl.find(somefilters, someoptions)`
+ *
+ * Or extend class `CrudRepositoryImpl` and override its functions:
+ * ```ts
+ * export class TestRepository extends CrudRepositoryImpl<Test> {
+ *   constructor(dataSource: DataSource, model: Test) {
+ *     super(dataSource, Customer);
+ *   }
+ *
+ *   // Override `deleteAll` to disable the operation
+ *   deleteAll(where?: Where, options?: Options) {
+ *     return Promise.reject(new Error('deleteAll is disabled'));
+ *   }
+ * }
+ * ```
+ */
+export class CrudRepositoryImpl<T extends Entity, ID>
+  implements EntityCrudRepository<T, ID>
+{
+  private connector: CrudConnector;
+  public readonly inclusionResolvers: Map<
+    string,
+    InclusionResolver<T, Entity>
+  > = new Map();
+
+  constructor(
+    public dataSource: DataSource,
+    // model should have type "typeof T", but that's not supported by TSC
+    public entityClass: typeof Entity & {prototype: T},
+  ) {
+    this.connector = dataSource.connector as CrudConnector;
+  }
+
+  private toModels(data: Promise<DataObject<Entity>[]>): Promise<T[]> {
+    return data.then(items => items.map(i => new this.entityClass(i) as T));
+  }
+
+  private toModel(data: Promise<DataObject<Entity>>): Promise<T> {
+    return data.then(d => new this.entityClass(d) as T);
+  }
+
+  create(entity: DataObject<T>, options?: Options): Promise<T> {
+    return this.toModel(
+      this.connector.create(this.entityClass, entity, options),
+    );
+  }
+
+  createAll(entities: DataObject<T>[], options?: Options): Promise<T[]> {
+    return this.toModels(
+      this.connector.createAll!(this.entityClass, entities, options),
+    );
+  }
+
+  async save(entity: DataObject<T>, options?: Options): Promise<T> {
+    if (typeof this.connector.save === 'function') {
+      return this.toModel(
+        this.connector.save(this.entityClass, entity, options),
+      );
+    } else {
+      const id = this.entityClass.getIdOf(entity);
+      if (id != null) {
+        await this.replaceById(id, entity, options);
+        return this.toModel(Promise.resolve(entity));
+      } else {
+        return this.create(entity, options);
+      }
+    }
+  }
+
+  find(filter?: Filter<T>, options?: Options): Promise<T[]> {
+    return this.toModels(
+      this.connector.find(this.entityClass, filter, options),
+    );
+  }
+
+  async findById(
+    id: ID,
+    filter?: FilterExcludingWhere<T>,
+    options?: Options,
+  ): Promise<T> {
+    if (typeof this.connector.findById === 'function') {
+      return this.toModel(
+        this.connector.findById(this.entityClass, id, options),
+      );
+    }
+    const where = this.entityClass.buildWhereForId(id);
+    const entities = await this.toModels(
+      this.connector.find(this.entityClass, {where: where}, options),
+    );
+    if (!entities.length) {
+      throw new EntityNotFoundError(this.entityClass, id);
+    }
+    return entities[0];
+  }
+
+  update(entity: DataObject<T>, options?: Options): Promise<void> {
+    return this.updateById(this.entityClass.getIdOf(entity), entity, options);
+  }
+
+  delete(entity: DataObject<T>, options?: Options): Promise<void> {
+    return this.deleteById(this.entityClass.getIdOf(entity), options);
+  }
+
+  updateAll(
+    data: DataObject<T>,
+    where?: Where<T>,
+    options?: Options,
+  ): Promise<Count> {
+    return this.connector.updateAll(this.entityClass, data, where, options);
+  }
+
+  async updateById(
+    id: ID,
+    data: DataObject<T>,
+    options?: Options,
+  ): Promise<void> {
+    let success: boolean;
+    if (typeof this.connector.updateById === 'function') {
+      success = await this.connector.updateById(
+        this.entityClass,
+        id,
+        data,
+        options,
+      );
+    } else {
+      const where = this.entityClass.buildWhereForId(id);
+      const result = await this.updateAll(data, where, options);
+      success = result.count > 0;
+    }
+    if (!success) {
+      throw new EntityNotFoundError(this.entityClass, id);
+    }
+  }
+
+  async replaceById(
+    id: ID,
+    data: DataObject<T>,
+    options?: Options,
+  ): Promise<void> {
+    let success: boolean;
+    if (typeof this.connector.replaceById === 'function') {
+      success = await this.connector.replaceById(
+        this.entityClass,
+        id,
+        data,
+        options,
+      );
+    } else {
+      // FIXME: populate inst with all properties
+      const inst = data;
+      const where = this.entityClass.buildWhereForId(id);
+      const result = await this.updateAll(data, where, options);
+      success = result.count > 0;
+    }
+    if (!success) {
+      throw new EntityNotFoundError(this.entityClass, id);
+    }
+  }
+
+  deleteAll(where?: Where<T>, options?: Options): Promise<Count> {
+    return this.connector.deleteAll(this.entityClass, where, options);
+  }
+
+  async deleteById(id: ID, options?: Options): Promise<void> {
+    let success: boolean;
+    if (typeof this.connector.deleteById === 'function') {
+      success = await this.connector.deleteById(this.entityClass, id, options);
+    } else {
+      const where = this.entityClass.buildWhereForId(id);
+      const result = await this.deleteAll(where, options);
+      success = result.count > 0;
+    }
+
+    if (!success) {
+      throw new EntityNotFoundError(this.entityClass, id);
+    }
+  }
+
+  count(where?: Where<T>, options?: Options): Promise<Count> {
+    return this.connector.count(this.entityClass, where, options);
+  }
+
+  exists(id: ID, options?: Options): Promise<boolean> {
+    if (typeof this.connector.exists === 'function') {
+      return this.connector.exists(this.entityClass, id, options);
+    } else {
+      const where = this.entityClass.buildWhereForId(id);
+      return this.count(where, options).then(result => result.count > 0);
+    }
+  }
+
+  execute(
+    command: Command,
+    parameters: NamedParameters | PositionalParameters,
+    options?: Options,
+  ): Promise<AnyObject> {
+    if (typeof this.connector.execute !== 'function') {
+      throw new Error('Not implemented');
+    }
+    return this.connector.execute(command, parameters, options);
+  }
+}

package/src/transaction.ts

@@ -0,0 +1,39 @@
+// 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
+
+/**
+ * Local transaction
+ */
+export interface Transaction {
+  /**
+   * Commit the transaction
+   */
+  commit(): Promise<void>;
+
+  /**
+   * Rollback the transaction
+   */
+  rollback(): Promise<void>;
+
+  /**
+   * Check if the transaction has an active connection
+   */
+  isActive(): boolean;
+
+  /**
+   * The transaction Identifier
+   */
+  id: string;
+}
+
+/**
+ * Isolation level
+ */
+export enum IsolationLevel {
+  READ_COMMITTED = 'READ COMMITTED', // default
+  READ_UNCOMMITTED = 'READ UNCOMMITTED',
+  SERIALIZABLE = 'SERIALIZABLE',
+  REPEATABLE_READ = 'REPEATABLE READ',
+}

package/src/type-resolver.ts

@@ -0,0 +1,98 @@
+// 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 {Class} from './common-types';
+
+/**
+ * A type resolver is a function that returns a class representing the type,
+ * typically a Model or Entity (e.g. Product).
+ *
+ * We use type resolvers to break require() loops when defining relations.
+ * The target model (class) is provided via a provider, thus deferring
+ * the actual reference to the class itself until later, when both sides
+ * of the relation are created as JavaScript classes.
+ *
+ * @typeParam Type - The type we are resolving, for example `Entity` or `Product`.
+ * This parameter is required.
+ *
+ * @typeParam StaticMembers - The static properties available on the
+ * type class. For example, all models have static `modelName` property.
+ * When `StaticMembers` are not provided, we default to static properties of
+ * a `Function` - `name`, `length`, `apply`, `call`, etc.
+ * Please note the value returned by the resolver is described as having
+ * arbitrary additional static properties (see how Class is defined).
+ */
+export type TypeResolver<
+  Type extends Object,
+  StaticMembers = Function,
+> = () => Class<Type> & StaticMembers;
+
+/**
+ * A function that checks whether a function is a TypeResolver or not.
+ * @param fn - The value to check.
+ */
+export function isTypeResolver<T extends object>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  fn: any,
+): fn is TypeResolver<T> {
+  // 1. A type provider must be a function
+  if (typeof fn !== 'function') return false;
+
+  // 2. A class constructor is not a type provider
+  if (/^class/.test(fn.toString())) return false;
+
+  // 3. Built-in types like Date & Array are not type providers
+  if (isBuiltinType(fn)) return false;
+
+  // TODO(bajtos): support model classes defined via ES5 constructor function
+
+  return true;
+}
+
+/**
+ * A boxed type for `null`
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function Null() {
+  return null;
+}
+
+/**
+ * Check if the provided function is a built-in type provided by JavaScript
+ * and/or Node.js. E.g. `Number`, `Array`, `Buffer`, etc.
+ */
+export function isBuiltinType(fn: Function): boolean {
+  return (
+    // scalars
+    fn === Number ||
+    fn === Boolean ||
+    fn === String ||
+    // objects
+    fn === Object ||
+    fn === Array ||
+    fn === Date ||
+    fn === RegExp ||
+    fn === Buffer ||
+    fn === Null ||
+    // function as a type
+    fn === Function
+  );
+}
+
+/**
+ * Resolve a type value that may have been provided via TypeResolver.
+ * @param fn - A type class or a type provider.
+ * @returns The resolved type.
+ */
+export function resolveType<T extends Object>(
+  fn: TypeResolver<T> | Class<T>,
+): Class<T>;
+
+// An overload to handle the case when `fn` is not a class nor a resolver.
+export function resolveType<T>(fn: T): T;
+
+export function resolveType<T>(fn: TypeResolver<T> | Class<T>) {
+  return isTypeResolver(fn) ? fn() : fn;
+}

package/src/types/any.ts

@@ -0,0 +1,38 @@
+// Copyright IBM Corp. 2017,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 {Type} from './type';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Any type
+ */
+export class AnyType implements Type<any> {
+  readonly name = 'any';
+
+  isInstance(value: any) {
+    return true;
+  }
+
+  isCoercible(value: any) {
+    return true;
+  }
+
+  defaultValue(): any {
+    return undefined;
+  }
+
+  coerce(value: any) {
+    return value;
+  }
+
+  serialize(value: any) {
+    if (value && typeof value.toJSON === 'function') {
+      return value.toJSON();
+    }
+    return value;
+  }
+}

package/src/types/array.ts

@@ -0,0 +1,53 @@
+// Copyright IBM Corp. 2017,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 util from 'util';
+import {Type} from './type';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Array type, such as string[]
+ */
+export class ArrayType<T> implements Type<T[]> {
+  constructor(public itemType: Type<T>) {}
+
+  readonly name = 'array';
+
+  isInstance(value: any) {
+    if (value == null) return true;
+    if (!Array.isArray(value)) {
+      return false;
+    }
+    const list = value as (T | null | undefined)[];
+    return list.every(i => this.itemType.isInstance(i));
+  }
+
+  isCoercible(value: any): boolean {
+    if (value == null) return true;
+    if (!Array.isArray(value)) {
+      return false;
+    }
+    return value.every(i => this.itemType.isCoercible(i));
+  }
+
+  defaultValue(): T[] {
+    return [];
+  }
+
+  coerce(value: any) {
+    if (value == null) return value;
+    if (!Array.isArray(value)) {
+      const msg = util.format('Invalid %s: %j', this.name, value);
+      throw new TypeError(msg);
+    }
+    return value.map(i => this.itemType.coerce(i));
+  }
+
+  serialize(value: T[] | null | undefined) {
+    if (value == null) return value;
+    return value.map(i => this.itemType.serialize(i));
+  }
+}

package/src/types/boolean.ts

@@ -0,0 +1,35 @@
+// Copyright IBM Corp. 2017,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 {Type} from './type';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Boolean type
+ */
+export class BooleanType implements Type<boolean> {
+  readonly name = 'boolean';
+
+  isInstance(value: any) {
+    return value == null || typeof value === 'boolean';
+  }
+
+  defaultValue() {
+    return false;
+  }
+
+  isCoercible(value: any): boolean {
+    return true;
+  }
+
+  coerce(value: any) {
+    return value == null ? value : Boolean(value);
+  }
+
+  serialize(value: boolean | null | undefined) {
+    return value;
+  }
+}