@loopback/repository 4.0.0-alpha.9 → 4.0.0

package/src/common-types.ts

@@ -0,0 +1,123 @@
+// 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
+
+/**
+ * Common types/interfaces such as Class/Constructor/Options/Callback
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Interface for classes with `new` operator and static properties/methods
+ */
+export interface Class<T> {
+  // new MyClass(...args) ==> T
+  new (...args: any[]): T;
+  // Other static properties/operations
+  [property: string]: any;
+}
+
+/**
+ * Interface for constructor functions without `new` operator.
+ *
+ * @example
+ * ```ts
+ * function Foo(x) {
+ *   if (!(this instanceof Foo)) { return new Foo(x); }
+ *   this.x = x;
+ * }
+ * ```
+ */
+export interface ConstructorFunction<T> {
+  (...args: any[]): T;
+}
+
+/**
+ * Constructor type - class or function
+ */
+export type Constructor<T> = Class<T> | ConstructorFunction<T>;
+
+/**
+ * Objects with open properties
+ */
+export interface AnyObject {
+  [property: string]: any;
+}
+
+/**
+ * An extension of the built-in Partial<T> type which allows partial values
+ * in deeply nested properties too.
+ */
+export type DeepPartial<T> =
+  | Partial<T> // handle free-form properties, e.g. DeepPartial<AnyObject>
+  | {[P in keyof T]?: DeepPartial<T[P]>};
+
+/**
+ * Type alias for strongly or weakly typed objects of T
+ */
+export type DataObject<T extends object> = T | DeepPartial<T>;
+
+/**
+ * Type alias for Node.js options object
+ */
+export type Options = AnyObject;
+
+/**
+ * Type alias for Node.js callback functions
+ */
+export type Callback<T> = (
+  err: Error | string | null | undefined,
+  result?: T,
+) => void;
+
+/**
+ * Type for a command
+ */
+export type Command = string | AnyObject;
+
+/**
+ * Named parameters, such as `{x: 1, y: 'a'}`
+ */
+export type NamedParameters = AnyObject;
+
+/**
+ * Positional parameters, such as [1, 'a']
+ */
+export type PositionalParameters = any[];
+
+/**
+ * Count of Model instances that were successful for methods like `updateAll`,
+ * `deleteAll`, etc.
+ */
+export interface Count {
+  count: number;
+}
+
+/**
+ * JSON Schema describing the Count interface. It's the response type for
+ * REST calls to APIs which return `count`. The type is compatible with
+ * `SchemaObject` from `@loopback/openapi-v3`, which is not an explicit
+ * dependency for `@loopback/repository`.
+ */
+export const CountSchema /* :SchemaObject */ = {
+  type: 'object' as const, // Force to be `object` type instead of `string`
+  title: 'loopback.Count',
+  'x-typescript-type': '@loopback/repository#Count',
+  properties: {
+    count: {
+      type: 'number' as const, // Force to be `number` type instead of `string`
+    },
+  },
+};
+
+/**
+ * Type helper to infer prototype from a constructor function.
+ *
+ * Example: `PrototypeOf<typeof Entity>` is resolved to `Entity`.
+ */
+export type PrototypeOf<Ctor extends Function> = Ctor extends {
+  prototype: infer Proto;
+}
+  ? Proto
+  : never;

package/src/connectors/connector.ts

@@ -0,0 +1,70 @@
+// 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 {
+  AnyObject,
+  Command,
+  NamedParameters,
+  Options,
+  PositionalParameters,
+} from '../common-types';
+import {Model} from '../model';
+
+/**
+ * Interfaces adopted by a {@link Connector}.
+ *
+ * @experimental
+ */
+export namespace ConnectorInterfaces {
+  /**
+   * Strong relation interfaces adopted by a {@link Connector}
+   *
+   * @experimental
+   */
+  export const enum StrongRelation {
+    BELONGS_TO = 'strongBelongsTo',
+    HAS_ONE = 'strongHasOne',
+    HAS_MANY = 'strongHasMany',
+    HAS_MANY_THROUGH = 'strongHasManyThrough',
+    HAS_AND_BELONGS_TO_MANY = 'strongHasAndBelongsToMany',
+    EMBEDS_ONE = 'strongEmbedsOne',
+    EMBEDS_MANY = 'strongEmbedsMany',
+    REFERNCES_MANY = 'strongReferencesMany',
+  }
+
+  /**
+   * Strong query join interfaces adopted by a {@link Connector}
+   *
+   * @experimental
+   */
+  export const enum StrongJoins {
+    INNER = 'strongInnerJoin',
+    LEFT = 'strongLeftJoin',
+    RIGHT = 'strongRightJoin',
+    FULL = 'strongFullJoin',
+    CARTESIAN = 'strongCartesianJoin',
+  }
+}
+
+/**
+ * Common properties/operations for connectors
+ */
+export interface Connector {
+  name: string; // Name/type of the connector
+  configModel?: Model; // The configuration model
+  interfaces?: (
+    | string
+    | ConnectorInterfaces.StrongRelation
+    | ConnectorInterfaces.StrongJoins
+  )[]; // A list of interfaces implemented by the connector
+  connect(): Promise<void>; // Connect to the underlying system
+  disconnect(): Promise<void>; // Disconnect from the underlying system
+  ping(): Promise<void>; // Ping the underlying system
+  execute?(
+    command: Command,
+    parameters: NamedParameters | PositionalParameters,
+    options?: Options,
+  ): Promise<AnyObject>;
+}

package/src/connectors/crud.connector.ts

@@ -0,0 +1,208 @@
+// 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, Where} from '@loopback/filter';
+import {Class, Count, Options} from '../common-types';
+import {Entity, EntityData} from '../model';
+import {Connector} from './connector';
+
+/**
+ * CRUD operations for connector implementations
+ */
+export interface CrudConnector extends Connector {
+  /**
+   * Create a new entity
+   * @param modelClass - The model class
+   * @param entity - The entity instance or data
+   * @param options - Options for the operation
+   * @returns A promise of the entity created
+   */
+  create(
+    modelClass: Class<Entity>,
+    entity: EntityData,
+    options?: Options,
+  ): Promise<EntityData>;
+
+  /**
+   * Create multiple entities
+   * @param modelClass - The model class
+   * @param entities - An array of entity instances or data
+   * @param options - Options for the operation
+   * @returns A promise of an array of entities created
+   */
+  createAll?(
+    modelClass: Class<Entity>,
+    entities: EntityData[],
+    options?: Options,
+  ): Promise<EntityData[]>;
+
+  /**
+   * Save an entity
+   * @param modelClass - The model class
+   * @param entity - The entity instance or data
+   * @param options - Options for the operation
+   * @returns A promise of the entity saved
+   */
+  save?(
+    modelClass: Class<Entity>,
+    entity: EntityData,
+    options?: Options,
+  ): Promise<EntityData>;
+
+  /**
+   * Find matching entities by the filter
+   * @param modelClass - The model class
+   * @param filter - The query filter
+   * @param options - Options for the operation
+   * @returns A promise of an array of entities found for the filter
+   */
+  find(
+    modelClass: Class<Entity>,
+    filter?: Filter,
+    options?: Options,
+  ): Promise<EntityData[]>;
+
+  /**
+   * Find an entity by id
+   * @param modelClass - The model class
+   * @param id - The entity id value
+   * @param options - Options for the operation
+   * @returns A promise of the entity found for the id
+   */
+  findById?<IdType>(
+    modelClass: Class<Entity>,
+    id: IdType,
+    options?: Options,
+  ): Promise<EntityData>;
+
+  /**
+   * Update an entity
+   * @param modelClass - The model class
+   * @param entity - The entity instance or data
+   * @param options - Options for the operation
+   * @returns Promise<true> if an entity is updated, otherwise
+   * Promise<false>
+   */
+  update?(
+    modelClass: Class<Entity>,
+    entity: EntityData,
+    options?: Options,
+  ): Promise<boolean>;
+
+  /**
+   * Delete an entity
+   * @param modelClass - The model class
+   * @param entity - The entity instance or data
+   * @param options - Options for the operation
+   * @returns Promise<true> if an entity is deleted, otherwise
+   * Promise<false>
+   */
+  delete?(
+    modelClass: Class<Entity>,
+    entity: EntityData,
+    options?: Options,
+  ): Promise<boolean>;
+
+  /**
+   * Update matching entities
+   * @param modelClass - The model class
+   * @param data - The data attributes to be updated
+   * @param where - The matching criteria
+   * @param options - Options for the operation
+   * @returns A promise of number of matching entities deleted
+   */
+  updateAll(
+    modelClass: Class<Entity>,
+    data: EntityData,
+    where?: Where<Entity>,
+    options?: Options,
+  ): Promise<Count>;
+
+  /**
+   * Update an entity by id
+   * @param modelClass - The model class
+   * @param id - The entity id value
+   * @param data - The data attributes to be updated
+   * @param options - Options for the operation
+   * @returns Promise<true> if an entity is updated for the id, otherwise
+   * Promise<false>
+   */
+  updateById?<IdType>(
+    modelClass: Class<Entity>,
+    id: IdType,
+    data: EntityData,
+    options?: Options,
+  ): Promise<boolean>;
+
+  /**
+   * Replace an entity by id
+   * @param modelClass - The model class
+   * @param id - The entity id value
+   * @param data - The data attributes to be updated
+   * @param options - Options for the operation
+   * @returns Promise<true> if an entity is replaced for the id, otherwise
+   * Promise<false>
+   */
+  replaceById?<IdType>(
+    modelClass: Class<Entity>,
+    id: IdType,
+    data: EntityData,
+    options?: Options,
+  ): Promise<boolean>;
+
+  /**
+   * Delete matching entities
+   * @param modelClass - The model class
+   * @param where - The matching criteria
+   * @param options - Options for the operation
+   * @returns A promise of number of matching entities deleted
+   */
+  deleteAll(
+    modelClass: Class<Entity>,
+    where?: Where<Entity>,
+    options?: Options,
+  ): Promise<Count>;
+
+  /**
+   * Delete an entity by id
+   * @param modelClass - The model class
+   * @param id - The entity id value
+   * @param options - Options for the operation
+   * @returns Promise<true> if an entity is deleted for the id, otherwise
+   * Promise<false>
+   */
+  deleteById?<IdType>(
+    modelClass: Class<Entity>,
+    id: IdType,
+    options?: Options,
+  ): Promise<boolean>;
+
+  /**
+   * Count matching entities
+   * @param modelClass - The model class
+   * @param where - The matching criteria
+   * @param options - Options for the operation
+   * @returns A promise of number of matching entities
+   */
+  count(
+    modelClass: Class<Entity>,
+    where?: Where<Entity>,
+    options?: Options,
+  ): Promise<Count>;
+
+  /**
+   * Check if an entity exists for the id
+   * @param modelClass - The model class
+   * @param id - The entity id value
+   * @param options - Options for the operation
+   * @returns Promise<true> if an entity exists for the id, otherwise
+   * Promise<false>
+   */
+  exists?<IdType>(
+    modelClass: Class<Entity>,
+    id: IdType,
+    options?: Options,
+  ): Promise<boolean>;
+}

package/src/connectors/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 './connector';
+export * from './crud.connector';
+export * from './kv.connector';

package/src/connectors/kv.connector.ts

@@ -0,0 +1,113 @@
+// 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} from '@loopback/filter';
+import {Class, Options} from '../common-types';
+import {Entity, EntityData} from '../model';
+import {Connector} from './connector';
+
+/**
+ * Key/Value operations for connector implementations
+ */
+export interface KVConnector<T extends Entity> extends Connector {
+  /**
+   * Delete an entry by key
+   * @param modelClass - Model class
+   * @param key - Key for the entry
+   * @param options - Options for the operation
+   * @returns Promise<true> if an entry is deleted for the id, otherwise
+   * Promise<false>
+   */
+  delete(
+    modelClass: Class<Entity>,
+    key: string,
+    options?: Options,
+  ): Promise<boolean>;
+
+  /**
+   * Delete all entries
+   * @param modelClass - Model class
+   * @param options - Options for the operation
+   * @returns A promise of the number of entries deleted
+   */
+  deleteAll(modelClass: Class<Entity>, options?: Options): Promise<number>;
+
+  /**
+   * Get an entry by key
+   * @param modelClass - Model class
+   * @param key - Key for the entry
+   * @param options - Options for the operation
+   * @returns A promise of the entry found for the key
+   */
+  get(modelClass: Class<Entity>, key: string, options?: Options): Promise<T>;
+
+  /**
+   * Set an entry with key/value
+   * @param modelClass - Model class
+   * @param key - Key for the entry
+   * @param value - Value for the entry
+   * @param options - Options for the operation
+   * @returns Promise<true> if an entry is set for the key, otherwise
+   * Promise<false>
+   */
+  set(
+    modelClass: Class<Entity>,
+    key: string,
+    value: EntityData,
+    options?: Options,
+  ): Promise<boolean>;
+
+  /**
+   * Set up ttl for an entry by key
+   * @param modelClass - Model class
+   * @param key - Key for the entry
+   * @param options - Options for the operation
+   * @returns Promise<true> if an entry is configured for the key, otherwise
+   * Promise<false>
+   */
+  expire(
+    modelClass: Class<Entity>,
+    key: string,
+    ttl: number,
+    options?: Options,
+  ): Promise<boolean>;
+
+  /**
+   * Get ttl for an entry by key
+   * @param modelClass - Model class
+   * @param key - Key for the entry
+   * @param ttl - Time to live in millisenconds
+   * @param options - Options for the operation
+   * @returns A promise of the TTL value
+   */
+  ttl?(
+    modelClass: Class<Entity>,
+    key: string,
+    ttl: number,
+    options?: Options,
+  ): Promise<number>;
+
+  /**
+   * Fetch all keys
+   * @param modelClass - Model class
+   * @param key - Key for the entry
+   * @param options - Options for the operation
+   * @returns A promise of an array of keys for all entries
+   */
+  keys?(modelClass: Class<Entity>, options?: Options): Promise<string[]>;
+
+  /**
+   * Get an Iterator for matching keys
+   * @param modelClass - Model class
+   * @param filter - Matching filter
+   * @param options - Options for the operation
+   * @returns A promise of an iterator of entries
+   */
+  iterateKeys?(
+    modelClass: Class<Entity>,
+    filter?: Filter,
+    options?: Options,
+  ): Promise<Iterator<T>>;
+}

package/src/datasource.ts

@@ -0,0 +1,37 @@
+// 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 {AnyObject, Options} from './common-types';
+import {Connector} from './connectors';
+
+/**
+ * DataSource denotes a configured connector
+ */
+export interface DataSource {
+  name: string; // Name of the data source
+  connector?: Connector; // The underlying connector instance
+
+  settings: AnyObject; // Settings
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [property: string]: any; // Other properties that vary by connectors
+}
+
+export interface SchemaMigrationOptions extends Options {
+  /**
+   * When set to 'drop', schema migration will drop existing tables and recreate
+   * them from scratch, removing any existing data along the way.
+   *
+   * When set to 'alter', schema migration will try to preserve current schema
+   * and data, and perform a non-destructive incremental update.
+   */
+  existingSchema?: 'drop' | 'alter';
+
+  /**
+   * List of model names to migrate.
+   *
+   * By default, all models are migrated.
+   */
+  models?: string[];
+}

package/src/decorators/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 './metadata';
+export * from './model.decorator';
+export * from './repository.decorator';

package/src/decorators/metadata.ts

@@ -0,0 +1,84 @@
+// 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 {InspectionOptions, MetadataInspector} from '@loopback/core';
+import {ModelDefinition, RelationDefinitionMap} from '../model';
+import {RELATIONS_KEY} from '../relations';
+import {
+  MODEL_KEY,
+  MODEL_PROPERTIES_KEY,
+  MODEL_WITH_PROPERTIES_KEY,
+  PropertyMap,
+} from './model.decorator';
+
+export class ModelMetadataHelper {
+  /**
+   * A utility function to simplify retrieving metadata from a target model and
+   * its properties.
+   * @param target - The class from which to retrieve metadata.
+   * @param options - An options object for the MetadataInspector to customize
+   * the output of the metadata retrieval functions.
+   */
+  static getModelMetadata(
+    target: Function,
+    options?: InspectionOptions,
+  ): ModelDefinition | {} {
+    const classDef = MetadataInspector.getClassMetadata(
+      MODEL_WITH_PROPERTIES_KEY,
+      target,
+      // https://github.com/loopbackio/loopback-next/issues/4721
+      // The `target` can be a subclass for a base model
+      {...options, ownMetadataOnly: true},
+    );
+    // Return the cached value, if it exists.
+    // XXX(kjdelisle): If we're going to support dynamic updates, then this
+    // will be problematic in the future, since it will never update.
+    if (classDef) {
+      return classDef;
+    } else {
+      const modelMeta = MetadataInspector.getClassMetadata<ModelDefinition>(
+        MODEL_KEY,
+        target,
+        options,
+      );
+      if (!modelMeta) {
+        return {};
+      } else {
+        // sets the metadata to a dedicated key if cached value does not exist
+
+        // set ModelDefinition properties if they don't already exist
+        const meta = new ModelDefinition({...modelMeta});
+
+        // set properties lost from creating instance of ModelDefinition
+        Object.assign(meta, modelMeta);
+
+        meta.properties = Object.assign(
+          <PropertyMap>meta.properties,
+          MetadataInspector.getAllPropertyMetadata(
+            MODEL_PROPERTIES_KEY,
+            target.prototype,
+            options,
+          ),
+        );
+
+        meta.relations = Object.assign(
+          <RelationDefinitionMap>meta.relations,
+          MetadataInspector.getAllPropertyMetadata(
+            RELATIONS_KEY,
+            target.prototype,
+            options,
+          ),
+        );
+
+        MetadataInspector.defineMetadata(
+          MODEL_WITH_PROPERTIES_KEY.key,
+          meta,
+          target,
+        );
+        return meta;
+      }
+    }
+  }
+}