mongoose-promise.d.ts

// Type definitions for Mongoose-Promise 4.5.4
// Project: http://mongoosejs.com/
// Definitions by: simonxca <https://github.com/simonxca/>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped

/*
 * These are the default promises included in the Mongoose v4.x
 * definitions. They will be deprecated beginning Mongoose V5.x
 * in favor of native ES6 Promises.
 *
 * You can switch the promise library that mongoose uses by:
 *
 * 1. Including this somewhere in your code:
 *    mongoose.Promise = YOUR_PROMISE;
 *
 * 2. Including this somewhere in your main .d.ts file:
 *    type MongoosePromise<T> = YOUR_PROMISE<T>;
 */

/*
 * http://mongoosejs.com/docs/api.html#promise-js
 *
 * Callback signatures are from the mPromise type definitions.
 */
interface MongoosePromise<T> {
  /**
   * Promise constructor.
   * Promises are returned from executed queries.
   * @param fn a function which will be called when the promise
   *   is resolved that accepts fn(err, ...){} as signature
   * @event err Emits when the promise is rejected
   * @event complete Emits when the promise is fulfilled
   * @deprecated Mongoose 5.0 will use native promises by default (or bluebird, if native
   *   promises are not present) but still support plugging in your own ES6-compatible
   *   promises library. Mongoose 5.0 will not support mpromise.
   */
  new(fn?: (err: any, arg: T) => void): MongoosePromise<T>;
  new(fn?: (err: any, ...args: T[]) => void): MongoosePromise<T>;
}

declare class MongoosePromise<T> {
  /**
   * Adds a single function as a listener to both err and complete.
   * It will be executed with traditional node.js argument position when the promise is resolved.
   * @deprecated Use onResolve instead.
   */
  addBack(listener: (err: any, arg: T) => void): this;
  addBack(listener: (err: any, ...args: T[]) => void): this;

  /**
   * Adds a listener to the complete (success) event.
   * @deprecated Adds a listener to the complete (success) event.
   */
  addCallback(listener: (arg: T) => void): this;
  addCallback(listener: (...args: T[]) => void): this;

  /**
   * Adds a listener to the err (rejected) event.
   * @deprecated Use onReject instead.
   */
  addErrback(listener: (err: any) => void): this;

  /** ES6-style .catch() shorthand */
  catch<TRes>(onReject?: (err: any) => void | TRes | PromiseLike<TRes>): MongoosePromise<TRes>;

  /**
   * Signifies that this promise was the last in a chain of then()s: if a handler passed
   * to the call to then which produced this promise throws, the exception will go uncaught.
   */
  end(): void;

  /**
   * Rejects this promise with err.
   * If the promise has already been fulfilled or rejected, not action is taken.
   * Differs from #reject by first casting err to an Error if it is not instanceof Error.
   */
  error(err: any): this;

  /**
   * Adds listener to the event.
   * If event is either the success or failure event and the event has already been emitted,
   * thelistener is called immediately and passed the results of the original emitted event.
   */
  on(event: string, listener: Function): this;

  /**
   * Rejects this promise with reason.
   * If the promise has already been fulfilled or rejected, not action is taken.
   */
  reject(reason: Object | string | Error): this;

  /**
   * Resolves this promise to a rejected state if err is passed or a fulfilled state if no err is passed.
   * If the promise has already been fulfilled or rejected, not action is taken.
   * err will be cast to an Error if not already instanceof Error.
   * NOTE: overrides mpromise#resolve to provide error casting.
   * @param err error or null
   * @param val value to fulfill the promise with
   */
  resolve(err?: any, val?: Object): this;

  /**
   * Creates a new promise and returns it. If onFulfill or onReject are passed, they are added as
   * SUCCESS/ERROR callbacks to this promise after the nextTick.
   * Conforms to promises/A+ specification.
   */
  then<TRes>(onFulFill: (arg: T) => void | TRes | PromiseLike<TRes>,
    onReject?: (err: any) => void | TRes | PromiseLike<TRes>): MongoosePromise<TRes>;
  then<TRes>(onFulfill: (...args: T[]) => void | TRes | PromiseLike<TRes>,
    onReject?: (err: any) => void | TRes | PromiseLike<TRes>): MongoosePromise<TRes>;

  /**
   * Fulfills this promise with passed arguments. Alias of mpromise#fulfill.
   * @deprecated Use fulfill instead.
   */
  complete(args: T): this;
  complete(...args: T[]): this;

  /** Fulfills this promise with passed arguments. */
  fulfill(...args: T[]): this;
  fulfill(arg: T): this;

  /** ES6-style promise constructor wrapper around mpromise. */
  static ES6<TRes>(resolver: (
    complete: (...args: TRes[]) => void | TRes | PromiseLike<TRes>,
    error: (e: any) => void | TRes | PromiseLike<TRes>
  ) => void): MongoosePromise<TRes>;
}