@loopback/repository 4.0.0-alpha.9 → 4.0.0

package/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) IBM Corp. 2017,2019.
+Node module: @loopback/repository
+This project is licensed under the MIT License, full text below.
+
+--------
+
+MIT license
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,469 +1,173 @@
 # @loopback/repository
 
-It provides a common set of interfaces for interacting with databases.
+This module provides a common set of interfaces for interacting with databases.
 
 ## Overview
 
-**NOTE**: This module is experimental and evolving. It is likely going to be
-refactored and decomposed into multiple modules as we refine the story based on
-the legacy `loopback-datasource-juggler` and connector modules from LoopBack
-3.x.
-
-This module provides data access facilities to various databases and services.
-It contains the constructs for modeling and accessing data. Repositories can be
-used alone or as part of `Controller` implementation.
+This module provides data access facilities to various databases and services as
+well as the constructs for modeling and accessing those data.
 
 ## Installation
 
-```
-$ npm install --save @loopback/repository
+```sh
+npm install --save @loopback/repository
 ```
 
 ## Basic use
 
+At the moment, we only have implementations of `Repository` based on LoopBack
+3.x `loopback-datasource-juggler` and connectors. The following steps illustrate
+how to define repositories and use them with controllers.
+
+### Defining a legacy datasource and a model
+
 The repository module provides APIs to define LoopBack 3.x data sources and
 models. For example,
 
 ```ts
-import {
-  DataSourceConstructor,
-  juggler,
-} from '@loopback/repository';
+// src/datasources/db.datasource.ts
+import {juggler} from '@loopback/repository';
 
-const ds: juggler.DataSource = new DataSourceConstructor({
+export const db: juggler.DataSource = new juggler.DataSource({
   name: 'db',
   connector: 'memory',
 });
-
-/* tslint:disable-next-line:variable-name */
-const Note = ds.createModel<typeof juggler.PersistedModel>(
-  'note',
-  {title: 'string', content: 'string'},
-  {},
-);
 ```
-A repository can be created directly using `DefaultCrudRepository`.
 
 ```ts
-  const repo = new DefaultCrudRepository(Note, ds);
-
-  // Bind the repository instance
-  ctx.bind('repositories.noteRepo').to(repo);
-```
-Fore more detailed info about the repository usage and implementation with a controller, please refer to [Use Repository](#use-repository)
-
-## Concepts
-
-### Repository
-
-`Repository` represents a specialized `Service` interface that provides
-strong-typed data access (for example, CRUD) operations of a domain model
-against the underlying database or service.
-
-`Repository` can be defined and implemented by application developers. LoopBack
-ships a few predefined `Repository` interfaces for typical CRUD and KV
-operations. Such `Repository` implements leverage `Model` definition and
-`DataSource` configuration to fulfill the logic for data access.
-
-```js
-interface Repository<T extends Model> {}
-
-interface CustomerRepository extends Repository<Customer> {
-  find(filter?: Filter, options?: Options): Promise<Customer[]>;
-  findByEmail(email: string): Promise<Customer>;
-  // ...
-}
-```
-
-See more examples at:
-- [Repository/CrudRepository/EntityRepository](src/repository.ts)
-- [KVRepository](src/kv-repository.ts)
-
-### Model
-
-A model describes business domain objects, for example, `Customer`, `Address`,
-and `Order`. It usually defines a list of properties with name, type, and other
-constraints.
-
-Models can be used for data exchange on the wire or between different systems.
-For example, a JSON object conforming to the `Customer` model definition can be
-passed in REST/HTTP payload to create a new customer or stored in a document
-database such as MongoDB. Model definitions can also be mapped to other forms,
-such as relational database schema, XML schema, JSON schema, OpenAPI schema, or
-gRPC message definition, and vice versa.
-
-There are two subtly different types of models for domain objects:
-
-- Value Object: A domain object that does not have an identity (ID). Its
-  equality is based on the structural value. For example, `Address` can be
-  modeled as `Value Object` as two US addresses are equal if they have the same
-  street number, street name, city, and zip code values. For example:
-  ```json
-  {
-    "name": "Address",
-    "properties": {
-      "streetNum": "string",
-      "streetName": "string",
-      "city": "string",
-      "zipCode": "string"
-    }
-  }
-  ```
-
-- Entity: A domain object that has an identity (ID). Its equality is based on
-  the identity. For example, `Customer` can be modeled as `Entity` as each
-  customer should have a unique customer id. Two instances of `Customer` with
-  the same customer id are equal since they refer to the same customer. For
-  example:
-  ```json
-  {
-    "name": "Customer",
-    "properties": {
-      "id": "string",
-      "lastName": "string",
-      "firstName": "string",
-      "email": "string",
-      "address": "Address"
-    }
-  }
-  ```
-
-### DataSource
-
-`DataSource` is a named configuration of a connector. The configuration
-properties vary by connectors. For example, a datasource for `MySQL` needs to
-set the `connector` property to `loopback-connector-mysql` with settings such
-as:
-```json
-{
-  "host": "localhost",
-  "port": 3306,
-  "user": "my-user",
-  "password": "my-password",
-  "database": "demo"
-}
-```
-
-When a `DataSource` is instantiated, the configuration properties will be used
-to initialize the connector to connect to the backend system.
-
-### Connector
-
-`Connector` is a provider that implements data access or api calls with a
-specific backend system, such as a database, a REST service, a SOAP Web Service,
-or a gRPC micro-service. It abstracts such interactions as a list of operations
-in the form of Node.js methods.
+// src/models/note.model.ts
+import {model, Entity, property} from '@loopback/repository';
 
-Typically, a connector translates LoopBack query
-and mutation requests into native api calls supported by the underlying Node.js
-driver for the given backend. For example, a connector for `MySQL` will map
-`create` method to SQL INSERT statement, which can be executed through MySQL
-driver for Node.js.
-
-### Mixin
-
-`Mixin` is a way of building up classes from reusable components by combining
-simpler partial classes, which can be modeled as `Mixin`.
-
-For example, the mixins belows add methods and properties to a base class to
-create a new one.
-
-```js
-// Mixin as a function
-function timestampMixin(Base) {
-  return class extends Base {
-    created: Date = new Date();
-    modified: Date = new Date();
-  }
-}
-
-// Mixin as an arrow function
-const fullNameMixin = Base => class extends Base {
-  fullName() {
-    return `${this.firstName} ${this.lastName}`;
-  }
-};
-
-// The base class
-class Customer {
+@model()
+export class Note extends Entity {
+  @property({id: true})
   id: string;
-  lastName: string;
-  firstName: string;
+  @property()
+  title: string;
+  @property()
+  content: string;
 }
 
-// Mix in timestamp
-const CustomerWithTS = timestampMixin(Customer);
-// Mix in full name
-const CustomerWithTSAndFullName = fullNameMixin(CustomerWithTS);
-```
-
-### Type
-
-To support property and parameter typing, LoopBack Next introduces an extensible
-typing system to capture the metadata and perform corresponding checks and
-coercion. The following types are supported out of box.
-
-- StringType
-- BooleanType
-- NumberType
-- DateType
-- BufferType
-- AnyType
-- ArrayType
-- UnionType
-
-## Use Repository
-The `Repository` and other interfaces extended from `Repository` provide access
-to backend databases and services. Repositories can be used alone or as part
-of `Controller` implementation.
-
-At the moment, we only have implementations of `Repository` based on LoopBack
-3.x `loopback-datasource-juggler` and connectors. The following steps illustrate
-how to define repositories and use them with controllers.
-
-### Define legacy data sources and models
-
-The repository module provides APIs to define LoopBack 3.x data sources and
-models. For example,
-
-```ts
-import {
-  DataSourceConstructor,
-  juggler,
-} from '@loopback/repository';
-
-const ds: juggler.DataSource = new DataSourceConstructor({
-  name: 'db',
-  connector: 'memory',
-});
+export interface NoteRelations {
+  // describe navigational properties here
+}
 
-/* tslint:disable-next-line:variable-name */
-const Note = ds.createModel<typeof juggler.PersistedModel>(
-  'note',
-  {title: 'string', content: 'string'},
-  {},
-);
+export type NoteWithRelations = Note & NoteRelations;
 ```
 
 **NOTE**: There is no declarative support for data source and model yet in
-LoopBack Next. These constructs need to be created programmatically as
-illustrated above.
+LoopBack 4. These constructs need to be created programmatically as illustrated
+above.
 
-### Define a repository
+### Defining a repository
 
-A repository can be created directly using `DefaultCrudRepository`.
+A repository can be created by extending `DefaultCrudRepository` and using
+dependency injection to resolve the datasource.
 
 ```ts
-  const repo = new DefaultCrudRepository(Note, ds);
-
-  // Bind the repository instance
-  ctx.bind('repositories.noteRepo').to(repo);
-```
-
-Alternatively, we can define a new Repository subclass and use dependency
-injection to resolve the data source and model.
-
-```ts
-class MyNoteRepository extends DefaultCrudRepository<Entity, string> {
-  constructor(
-    @inject('models.Note') myModel: typeof juggler.PersistedModel,
-    // FIXME For some reason ts-node fails by complaining that
-    // juggler is undefined if the following is used:
-    // @inject('dataSources.memory') dataSource: juggler.DataSource
-    // tslint:disable-next-line:no-any
-    @inject('dataSources.memory') dataSource: any) {
-      super(myModel, dataSource);
-    }
+// src/repositories/note.repository.ts
+import {DefaultCrudRepository, DataSourceType} from '@loopback/repository';
+import {Note, NoteRelations} from '../models';
+import {inject} from '@loopback/core';
+
+export class NoteRepository extends DefaultCrudRepository<
+  Note,
+  typeof Note.prototype.id,
+  NoteRelations
+> {
+  constructor(@inject('datasources.db') protected dataSource: DataSourceType) {
+    super(Note, dataSource);
+  }
 }
 ```
 
-### Define a controller
+### Defining a controller
 
 Controllers serve as handlers for API requests. We declare controllers as
 classes with optional dependency injection by decorating constructor parameters
 or properties.
 
 ```ts
-import {Context, inject} from '@loopback/context';
-
-import {
-  repository,
-  Entity,
-  Options,
-  DataObject,
-  Filter,
-  EntityCrudRepository,
-} from '@loopback/repository';
-
-// The Controller for Note
-class NoteController {
+// src/controllers/note.controller.ts
+import {repository} from '@loopback/repository';
+import {NoteRepository} from '../repositories';
+import {Note} from '../models';
+import {post, requestBody, get, param} from '@loopback/rest';
+
+export class NoteController {
   constructor(
     // Use constructor dependency injection to set up the repository
-    @repository('noteRepo')
-    public noteRepo: EntityCrudRepository<Entity, number>,
+    @repository(NoteRepository) public noteRepo: NoteRepository,
   ) {}
 
   // Create a new note
-  create(data: DataObject<Entity>, options?: Options) {
-    return this.noteRepo.create(data, options);
+  @post('/note')
+  create(@requestBody() data: Note) {
+    return this.noteRepo.create(data);
   }
 
   // Find notes by title
-  findByTitle(title: string, options?: Options) {
-    return this.noteRepo.find({where: {title}}, options);
+  @get('/note/{title}')
+  findByTitle(@param.path.string('title') title: string) {
+    return this.noteRepo.find({where: {title}});
   }
 }
 ```
 
-Alternatively, the controller can be declared using property injection:
-
-```ts
-class NoteController {
-  @repository('noteRepo')
-  public noteRepo: EntityCrudRepository<Entity, number>;
-}
-```
-
 ### Run the controller and repository together
 
-#### Bind the repository to context
-
-```ts
-// Create a context
-const ctx = new Context();
-
-// Mock up a predefined repository
-const repo = new DefaultCrudRepository(Note, ds);
-
-// Bind the repository instance
-ctx.bind('repositories.noteRepo').to(repo);
-```
-
-```ts
-// Create a context
-const ctx = new Context();
-
-// Bind model `Note`
-ctx.bind('models.Note').to(Note);
-
-// Bind the in-memory DB dataSource
-ctx.bind('dataSources.memory').to(ds);
-
-// Bind the repository class
-ctx.bind('repositories.noteRepo').toClass(MyNoteRepository);
-```
-
 #### Using the Repository Mixin for Application
-A Repository Mixin is available for Application that provides convenience methods for binding and instantiating a repository class. Bound instances can be used anywhere in your application using Dependency Injection. An array set to the key `repositories` can be passed to the constructor or the `.repository(RepositoryClass)` function can be used. The mixin will also instantiate any repositories declared by a component in its constructor using the `repositories` key.
 
-Repositories will be bound to the key `repositories.RepositoryClass` where `RepositoryClass` is the name of the Repository class being bound.
-```ts
-import { Application } from '@loopback/core';
-import { RepositoryMixin } from '@loopback/repository';
-import { ProductRepository, CategoryRepository } from './repository';
+A Repository Mixin is available for Application that provides convenience
+methods for binding and instantiating a repository class. Bound instances can be
+used anywhere in your application using Dependency Injection. The
+`.repository(RepositoryClass)` function can be used to bind a repository class
+to an Application. The mixin will also instantiate any repositories declared by
+a component in its constructor using the `repositories` key.
 
-// Using the Mixin
-class MyApplication extends RepositoryMixin(Application) {}
+Repositories will be bound to the key `repositories.RepositoryClass` where
+`RepositoryClass` is the name of the Repository class being bound.
 
-// ProductRepository will be bound to key `repositories.ProductRepository`
-const app = new MyApplication({repositories: [ProductRepository]});
-// CategoryRepository will be bound to key `repositories.CategoryRepository`
-app.repository(CategoryRepository);
-```
-
-### Compose repositories and controllers in a context
+We'll use `BootMixin` on top of `RepositoryMixin` so that Repository bindings
+can be taken care of automatically at boot time before the application starts.
 
 ```ts
-async function main() {
-  // Create a context
-  const ctx = new Context();
-
-  // Mock up a predefined repository
-  const repo = new DefaultCrudRepository(Note, ds);
-
-  // Bind the repository instance
-  ctx.bind('repositories.noteRepo').to(repo);
-
-  // Bind the controller class
-  ctx.bind('controllers.MyController').toClass(NoteController);
-
-  // Resolve the controller
-  const controller: NoteController = await ctx.get('controllers.MyController');
-
-  // Create some notes
-  await controller.create({title: 't1', content: 'Note 1'});
-  await controller.create({title: 't2', content: 'Note 2'});
-
-  // Find notes by title
-  const notes = await controller.findByTitle('t1');
-  return notes;
-}
-
-// Invoke the example
-main().then(notes => {
-  // It should print `Notes [ { title: 't1', content: 'Note 1', id: 1 } ]`
-  console.log('Notes', notes);
-});
-```
-
-### Mix in a repository into the controller (To be implemented)
-
-This style allows repository methods to be mixed into the controller class
-to mimic LoopBack 3.x style model classes with remote CRUD methods. It blends
-the repository responsibility/capability into the controller.
-
-```js
-import {EntityCrudRepository} from '../../src/repository';
-import {Customer} from '../models/customer';
-import {repository} from "../../src/decorator";
-
-/**
- * Use class level @repository decorator to mixin repository methods into the
- * controller class. Think about @repository as a shortcut to @mixin(...)
- */
-// Style 1
-// Create a repository that binds Customer to mongodbDataSource
-@repository(Customer, 'mongodbDataSource')
-// Style 2
-// Reference a pre-configured repository by name. This is close to LoopBack
-// 3.x model-config.json
-// @repository('myCustomerRepository')
-export class CustomerController {
-  // find() will be mixed in
-}
-```
-
-## Declare pre-defined repositories in JSON/YAML (To be implemented)
-
-Repositories can be declared in JSON/YAML files as follows:
-
-server/repositories.json
-```json
-{
-  "customerRepo": {
-    "dataSource": "mysql",
-    "model": "Customer",
-    "settings": {}
+import {BootMixin} from '@loopback/boot';
+import {ApplicationConfig} from '@loopback/core';
+import {RepositoryMixin} from '@loopback/repository';
+import {RestApplication} from '@loopback/rest';
+import {db} from './datasources/db.datasource';
+
+export class RepoApplication extends BootMixin(
+  RepositoryMixin(RestApplication),
+) {
+  constructor(options?: ApplicationConfig) {
+    super(options);
+    this.projectRoot = __dirname;
+    this.dataSource(db);
   }
 }
 ```
+
 ## Related resources
-- https://martinfowler.com/eaaCatalog/repository.html
-- https://msdn.microsoft.com/en-us/library/ff649690.aspx
-- http://docs.spring.io/spring-data/data-commons/docs/2.0.0.M3/reference/html/#repositories
+
+- <https://martinfowler.com/eaaCatalog/repository.html>
+- <https://msdn.microsoft.com/en-us/library/ff649690.aspx>
+- <http://docs.spring.io/spring-data/data-commons/docs/2.0.0.M3/reference/html/#repositories>
 
 ## Contributions
 
-- [Guidelines](https://github.com/strongloop/loopback-next/wiki/Contributing##guidelines)
-- [Join the team](https://github.com/strongloop/loopback-next/issues/110)
+- [Guidelines](https://github.com/loopbackio/loopback-next/blob/master/docs/CONTRIBUTING.md)
+- [Join the team](https://github.com/loopbackio/loopback-next/issues/110)
 
 ## Tests
 
-run 'npm test' from the root folder.
+Run `npm test` from the root folder.
 
 ## Contributors
 
-See [all contributors](https://github.com/strongloop/loopback-next/graphs/contributors).
+See
+[all contributors](https://github.com/loopbackio/loopback-next/graphs/contributors).
 
 ## License
 

package/dist/common-types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Common types/interfaces such as Class/Constructor/Options/Callback
+ */
+/**
+ * Interface for classes with `new` operator and static properties/methods
+ */
+export interface Class<T> {
+    new (...args: any[]): T;
+    [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 declare 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 declare type DeepPartial<T> = Partial<T> | {
+    [P in keyof T]?: DeepPartial<T[P]>;
+};
+/**
+ * Type alias for strongly or weakly typed objects of T
+ */
+export declare type DataObject<T extends object> = T | DeepPartial<T>;
+/**
+ * Type alias for Node.js options object
+ */
+export declare type Options = AnyObject;
+/**
+ * Type alias for Node.js callback functions
+ */
+export declare type Callback<T> = (err: Error | string | null | undefined, result?: T) => void;
+/**
+ * Type for a command
+ */
+export declare type Command = string | AnyObject;
+/**
+ * Named parameters, such as `{x: 1, y: 'a'}`
+ */
+export declare type NamedParameters = AnyObject;
+/**
+ * Positional parameters, such as [1, 'a']
+ */
+export declare 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 declare const CountSchema: {
+    type: "object";
+    title: string;
+    'x-typescript-type': string;
+    properties: {
+        count: {
+            type: "number";
+        };
+    };
+};
+/**
+ * Type helper to infer prototype from a constructor function.
+ *
+ * Example: `PrototypeOf<typeof Entity>` is resolved to `Entity`.
+ */
+export declare type PrototypeOf<Ctor extends Function> = Ctor extends {
+    prototype: infer Proto;
+} ? Proto : never;