Add typescript type definitions

.gitignore

@@ -13,5 +13,5 @@ npm-debug.log
 .project
 test/memory.json
 .nyc_output
-
+dist
 

index.d.ts

@@ -0,0 +1,36 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: loopback-datasource-juggler
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+// Type definitions for loopback-datasource-juggler 3.x
+// Project: https://github.com/strongloop/loopback-datasource-juggler
+// Definitions by: Raymond Feng <https://github.com/raymondfeng>
+// TypeScript Version: 2.8
+
+/**
+ * Experimental TypeScript definitions to capture types of the key artifacts
+ * from `loopback-datasource-juggler` module. One of the main purposes is to
+ * leverage such types in `LoopBack 4`'s bridge to juggler.
+ *
+ * Please note some of the classes, properties, methods, and functions are
+ * intentionally not included in the definitions because of one of the following
+ * factors:
+ *
+ * - They are internal
+ * - They are to be deprecated
+ */
+export * from './types/common';
+export * from './types/model';
+export * from './types/relation';
+export * from './types/query';
+export * from './types/datasource';
+export * from './types/kv-model';
+export * from './types/persisted-model';
+export * from './types/scope';
+export * from './types/transaction-mixin';
+export * from './types/relation-mixin';
+export * from './types/observer-mixin';
+export * from './types/validation-mixin';
+export * from './types/inclusion-mixin';
+export * from './types/connector';

package.json

@@ -22,14 +22,16 @@
     "url": "https://github.com/strongloop/loopback-datasource-juggler"
   },
   "main": "index.js",
+  "types": "index.d.ts",
   "browser": {
     "depd": "./lib/browser.depd.js"
   },
   "scripts": {
     "coverage": "nyc report --reporter=text-lcov | coveralls",
     "lint": "eslint .",
+    "tsc": "tsc -p tsconfig.json --outDir dist",
     "test": "nyc mocha",
-    "posttest": "npm run lint"
+    "posttest": "npm run tsc && npm run lint"
   },
   "devDependencies": {
     "async-iterators": "^0.2.2",
@@ -40,9 +42,11 @@
     "loopback-connector-throwing": "file:./test/fixtures/loopback-connector-throwing",
     "mocha": "^3.2.0",
     "nyc": "^11.1.0",
-    "should": "^8.4.0"
+    "should": "^8.4.0",
+    "typescript": "^2.8.3"
   },
   "dependencies": {
+    "@types/node": "^10.0.3",
     "async": "~2.1.4",
     "bluebird": "^3.1.1",
     "debug": "^3.1.0",

tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+
+    "lib": ["es2018", "dom"],
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "target": "es2017",
+    "sourceMap": true,
+    "declaration": true
+  },
+  "include": ["types/", "index.d.ts"],
+  "exclude": ["node_modules/**"]
+}

types/common.d.ts

@@ -0,0 +1,28 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: loopback-datasource-juggler
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+/**
+ * Objects with open properties
+ */
+export interface AnyObject<T = any> {
+  [property: string]: T;
+}
+
+/**
+ * Type alias for options object
+ */
+export type Options = AnyObject<any>;
+
+/**
+ * Type alias for Node.js callback functions
+ */
+export type Callback<T = any> = (err: any, result?: T) => void;
+
+/**
+ * Return export type for promisified Node.js async methods.
+ *
+ * Note that juggler uses Bluebird, not the native Promise.
+ */
+export type PromiseOrVoid<T = any> = PromiseLike<T> | void;

types/connector.d.ts

@@ -0,0 +1,46 @@
+import {Callback, DataSource, Options, PromiseOrVoid} from '..';
+
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: loopback-datasource-juggler
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+/**
+ * Connector from `loopback-connector` module
+ */
+export interface Connector {
+  name: string; // Name/type of the connector
+  dataSource?: DataSource;
+  connect(callback?: Callback): PromiseOrVoid; // Connect to the underlying system
+  disconnect(callback?: Callback): PromiseOrVoid; // Disconnect from the underlying system
+  ping(callback?: Callback): PromiseOrVoid; // Ping the underlying system
+  execute?(...args: any[]): Promise<any>;
+}
+
+/**
+ * Base connector class
+ */
+export declare class ConnectorBase implements Connector {
+  name: string; // Name/type of the connector;
+  dataSource?: DataSource;
+  connect(callback?: Callback): PromiseOrVoid; // Connect to the underlying system
+  disconnect(callback?: Callback): PromiseOrVoid; // Disconnect from the underlying system
+  ping(callback?: Callback): PromiseOrVoid; // Ping the underlying system
+  execute?(...args: any[]): Promise<any>;
+
+  /**
+   * Initialize the connector against the given data source
+   *
+   * @param {DataSource} dataSource The dataSource
+   * @param {Function} [callback] The callback function
+   */
+  static initialize(dataSource: DataSource, callback?: Callback): void;
+
+  constructor(settings?: Options);
+}
+
+export declare class Memory extends ConnectorBase {}
+
+export declare class KeyValueMemoryConnector extends ConnectorBase {}
+
+export declare class Transient extends ConnectorBase {}

types/datasource.d.ts

@@ -0,0 +1,176 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: loopback-datasource-juggler
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {AnyObject, Callback, Options, PromiseOrVoid} from './common';
+import {
+  ModelBaseClass,
+  ModelBuilder,
+  ModelDefinition,
+  PropertyDefinition,
+} from './model';
+
+/**
+ * LoopBack models can manipulate data via the DataSource object.
+ * Attaching a `DataSource` to a `Model` adds instance methods and static methods to the `Model`.
+ *
+ * Define a data source to persist model data.
+ * To create a DataSource programmatically, call `createDataSource()` on the LoopBack object; for example:
+ * ```js
+ * var oracle = loopback.createDataSource({
+ *   connector: 'oracle',
+ *   host: '111.22.333.44',
+ *   database: 'MYDB',
+ *   username: 'username',
+ *   password: 'password'
+ * });
+ * ```
+ *
+ * All classes in single dataSource share same the connector type and
+ * one database connection.
+ *
+ * For example, the following creates a DataSource, and waits for a connection callback.
+ *
+ * ```
+ * var dataSource = new DataSource('mysql', { database: 'myapp_test' });
+ * dataSource.define(...);
+ * dataSource.on('connected', function () {
+ *     // work with database
+ * });
+ * ```
+ * @class DataSource
+ * @param {String} [name] Optional name for datasource.
+ * @options {Object} settings Database-specific settings to establish connection (settings depend on specific connector).
+ * The table below lists a typical set for a relational database.
+ * @property {String} connector Database connector to use.  For any supported connector, can be any of:
+ *
+ * - The connector module from `require(connectorName)`.
+ * - The full name of the connector module, such as 'loopback-connector-oracle'.
+ * - The short name of the connector module, such as 'oracle'.
+ * - A local module under `./connectors/` folder.
+ * @property {String} host Database server host name.
+ * @property {String} port Database server port number.
+ * @property {String} username Database user name.
+ * @property {String} password Database password.
+ * @property {String} database Name of the database to use.
+ * @property {Boolean} debug Display debugging information. Default is false.
+ *
+ * The constructor allows the following styles:
+ *
+ * 1. new DataSource(dataSourceName, settings). For example:
+ *   - new DataSource('myDataSource', {connector: 'memory'});
+ *   - new DataSource('myDataSource', {name: 'myDataSource', connector: 'memory'});
+ *   - new DataSource('myDataSource', {name: 'anotherDataSource', connector: 'memory'});
+ *
+ * 2. new DataSource(settings). For example:
+ *   - new DataSource({name: 'myDataSource', connector: 'memory'});
+ *   - new DataSource({connector: 'memory'});
+ *
+ * 3. new DataSource(connectorModule, settings). For example:
+ *   - new DataSource(connectorModule, {name: 'myDataSource})
+ *   - new DataSource(connectorModule)
+ */
+export declare class DataSource {
+  name: string;
+  settings: Options;
+
+  connected?: boolean;
+  connecting?: boolean;
+
+  connector?: any;
+
+  DataAccessObject: AnyObject & {prototype: AnyObject};
+
+  constructor(name?: string, settings?: Options, modelBuilder?: ModelBuilder);
+
+  constructor(
+    connectorModule: object,
+    settings?: Options,
+    modelBuilder?: ModelBuilder,
+  );
+
+  /**
+   * Create a model class
+   * @param name Name of the model
+   * @param properties An object of property definitions
+   * @param options Options for model settings
+   */
+  createModel<T extends ModelBaseClass>(
+    name: string,
+    properties?: AnyObject,
+    options?: Options,
+  ): T;
+
+  getModel(modelName: string): ModelBaseClass | undefined;
+
+  /**
+   * Attach an existing model to a data source.
+   * This will mixin all of the data access object functions (DAO) into your
+   * modelClass definition.
+   * @param {ModelBaseClass} modelClass The model constructor that will be enhanced
+   * by DataAccessObject mixins.
+   */
+  attach(modelClass: ModelBaseClass): ModelBaseClass;
+
+  automigrate(models: string | string[], callback?: Callback): PromiseOrVoid;
+
+  autoupdate(models: string | string[], callback?: Callback): PromiseOrVoid;
+
+  discoverModelDefinitions(
+    options?: Options,
+    callback?: Callback<ModelDefinition[]>,
+  ): PromiseOrVoid<ModelDefinition[]>;
+
+  discoverModelProperties(
+    modelName: string,
+    options?: Options,
+    callback?: Callback<PropertyDefinition[]>,
+  ): PromiseOrVoid<PropertyDefinition[]>;
+
+  discoverPrimaryKeys(
+    modelName: string,
+    options?: Options,
+    callback?: Callback<PropertyDefinition[]>,
+  ): PromiseOrVoid<PropertyDefinition[]>;
+
+  discoverForeignKeys(
+    modelName: string,
+    options?: Options,
+    callback?: Callback<PropertyDefinition[]>,
+  ): PromiseOrVoid<PropertyDefinition[]>;
+
+  discoverExportedForeignKeys(
+    modelName: string,
+    options?: Options,
+    callback?: Callback<PropertyDefinition[]>,
+  ): PromiseOrVoid<PropertyDefinition[]>;
+
+  discoverAndBuildModels(
+    modelName: string,
+    options?: Options,
+    callback?: Callback<{[name: string]: ModelBaseClass}>,
+  ): PromiseOrVoid<{[name: string]: ModelBaseClass}>;
+
+  discoverSchema(
+    tableName: string,
+    options?: Options,
+    callback?: Callback<AnyObject>,
+  ): PromiseOrVoid<AnyObject>;
+
+  discoverSchemas(
+    tableName: string,
+    options?: Options,
+    callback?: Callback<AnyObject[]>,
+  ): PromiseOrVoid<AnyObject[]>;
+
+  buildModelFromInstance(
+    modelName: string,
+    jsonObject: AnyObject,
+    options?: Options,
+  ): ModelBaseClass;
+
+  connect(callback?: Callback): PromiseOrVoid;
+  disconnect(callback?: Callback): PromiseOrVoid;
+  ping(callback?: Callback): PromiseOrVoid;
+}

types/inclusion-mixin.d.ts

@@ -0,0 +1,44 @@
+// Copyright IBM Corp. 2018. All Rights Reserved.
+// Node module: loopback-datasource-juggler
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/licenses/MIT
+
+import {PersistedData, PersistedModel} from '..';
+import {Callback, Options, PromiseOrVoid} from './common';
+import {Inclusion} from './query';
+
+/**
+ * Inclusion mixin
+ */
+export interface InclusionMixin {
+  /**
+   * Enables you to load relations of several objects and optimize numbers of requests.
+   *
+   * Examples:
+   *
+   * Load all users' posts with only one additional request:
+   * `User.include(users, 'posts', function() {});`
+   * Or
+   * `User.include(users, ['posts'], function() {});`
+   *
+   * Load all users posts and passports with two additional requests:
+   * `User.include(users, ['posts', 'passports'], function() {});`
+   *
+   * Load all passports owner (users), and all posts of each owner loaded:
+   *```Passport.include(passports, {owner: 'posts'}, function() {});
+   *``` Passport.include(passports, {owner: ['posts', 'passports']});
+   *``` Passport.include(passports, {owner: [{posts: 'images'}, 'passports']});
+   *
+   * @param {Array} objects Array of instances
+   * @param {String|Object|Array} include Which relations to load.
+   * @param {Object} [options] Options for CRUD
+   * @param {Function} cb Callback called when relations are loaded
+   *
+   */
+  include<T extends PersistedModel>(
+    objects: PersistedData<T>[],
+    include: Inclusion,
+    options?: Options,
+    callback?: Callback<PersistedData<T>[]>,
+  ): PromiseOrVoid<PersistedData<T>[]>;
+}