#29

[aligilak]

"use strict";

// -- kriskowal Kris Kowal Copyright (C) 2009-2010 MIT License
// -- kriszyp Kris Zyp

/*

Basic events, signals, emitters, observers, observables,
deferreds, and promises.

Typical usage:

    var Q = require("narwhal/promise");
    var {promise, resolve, reject} = Q.defer();
    asyncOperation(function () {
        try {
            resolve("ok result");
        } catch (exception) {
            reject(exception);
        }
    });
    return promise;

    // meanwhile...

    Q.when(promise, function (value) {
        print("ok " + value);
    });

Optionally accepts an errback and progress notifier:

    Q.when(promise, function (value) {
        print("ok " + value);
    }, function (error) {
        print("error " + value);
    }, function (progress) {
        print("progress " + progress.toFixed(1) + "%");
    });

Object-oriented variation:

    // "then" and "when" are both acceptable
    promise.then(function (value) {
        print("ok " + value);
    });

Using event emitters:

    deferred.observe("ok", function (value) { });
    deferred.observe("error", function (value) { });
    deferred.observe("cancel", function (value) { });
    deferred.observe("progress", function (progress) { });

    promise.observe("ok", function (value) { });
    promise.observe("error", function (value) { });
    promise.observe("cancel", function (value) { });
    promise.observe("progress", function (progress) { });

Continued deferrence works:

    var resolution = Q.when(async1(), function () {
        return Q.when(async2(), function () {
            return Q.when(async3(), function () {
                return resolution;
            };
        });
    });

    Q.when(resolution, function () {
        print(resolution);
    });

*/

// Authors and their contributions:

// Tyler Close
// Waterken

// Built on the shoulders of Tyler Close's Waterken "ref_send" API,
// with some chance of falling short. Instead of a purely
// functional API, where a promise is a function that takes a method
// name as its first argument, "Promise" is a JavaScript type that
// implements an "emit" method, analogous to "ref_send's" internal
// "forward" method. The "emit" method comes from an event
// "Emitter" base type, inspired by "Node" and Chiron's
// "Observable/Signaler" events system. The "emit" method emits an
// event to the corresponding method, if it exists. As in
// "ref_send", "Promise" is a duck-type so different varieties and
// extensions to the "Promise" API are possible in user-land.
//
// Also, to take advantage of JavaScript native facilities, the
// function for grabbing a "near" value from a "Reference" promise
// object is "valueOf()".

// Distinct in this implementation, the concern of how to implement
// the event loop has been separated into an external module. The
// implementation of this module necessarily varries across engines.

// Unlike "ref_send" originally, "undefined" is an acceptable value
// for a resolved promise reference. This permits the natural use
// of promises for events that have no meaningful value, like the
// DOM's "DOM ready" event which would be better represented as a
// promise since observers of the "event" after the fact should have
// a signal emitted immediately.

// -- kriszyp Kris Zyp

// Based on the CommonJS spec for promises,
// http://wiki.commonjs.org/wiki/Promises
// and the Dojo Deferred API.

// While Deferreds are compatible with the Dojo API, internally they
// are a "ref_send" "promise", "resolver" pair. For security
// purposes, you must return only the "promise" component of the
// "Deferred" to suspicious callers, and it's recommended that all
// API's make a habbit of returning only the "promise". The parts
// of the Deferred API that are relevant for promise consumers are
// hosted on both the "Deferred" object and the "Promise" object but
// are the sole responsibility of the "Promise". All the parts of
// the Deferred API that are relevant for resolving a promise are
// only on the Deferred object.

// ryah Ryan Dahl
// NodeJS

// EventEmitter, Promise. NodeJS's Promise API resembles the Dojo
// API but are called Promises. Ryan also provided a critcal insight
// that a Promise or Deferred could be implemented in terms of
// an event emitter framework.

// kriskowal Kris Kowal Copyright 2009-2010 MIT License
// Narwhal, Chiron

// Carrying Ryan Dahl's epiphany to its logical conclusion, I've
// ported Chiron's "events" module, which includes base types for
// events, signals, emitters, observers, an observable method type.
// It is suitable for hosting DOM-style events, where signals have
// an intrinsic "default" action that can be cancelled, and can
// propagate but be stopped. Chiron had a "Signaler" type, which
// I've renamed "Emitter" to converge with NodeJS.

// Depends on ES5 Object.create and Object.freeze.

var Q = exports;

Q.enqueue = require("event-loop").enqueue;

/**

• An activation object for event observers that permits an observer to affect
• whether the an event continues to propagate to other observers and whether
• the emitting signal completes its default action.
  */

Q.Event = function () {
var self = Object.create(Q.Event.prototype);
Q.Event.constructor.call(self);
return Object.freeze(Object.create(self));
};

Q.Event.constructor = Object.freeze(function () {
var self = this;

var propagation = true;
var defaulting = true;

/**
 * prevents further propagation and the default action of the emitting
 * signal.
 */
self.stop = Object.freeze(function () {
    self.stopPropagation();
    self.cancelDefault();
});

/**
 * prevents further propagation of the emitting signal
 */
self.stopPropagation = Object.freeze(function () {
    propagation = false;
});

/**
 * prevents the default action of the emitting signal.
 */
self.cancelDefault = Object.freeze(function () {
    defaulting = false;
});

/**
 * @returns {Boolean} whether this event instructs the emitting signal to
 * continue propagating to further observers.
 */
self.getPropagation = Object.freeze(function () {
    return propagation;
});

/**
 * @returns {Boolean} whether this event instructs the emitting signal to
 * apply its default action.
 */
self.getDefaulting = Object.freeze(function () {
    return defaulting;
});

});

Object.freeze(Q.Event);
Object.freeze(Q.Event.prototype);

/** Signal

• base prototype for a signal that emits events.
  */

Q.Signal = function (action, Event) {
var self = Object.create(Q.Signal.prototype);
Q.Signal.constructor.call(self, action, Event);
return Object.freeze(Object.create(self));
};

Q.Signal.constructor = Object.freeze(function (action, Event) {
var self = this;

var waiting = [];
if (!Event)
    Event = Q.Event;

/**
 * arranges for a given observer function to be called whenever
 * this signal is emitted.  The calling of this observer
 * function can in turn be observed by the returned signal.
 *
 * @param observer {Function} a function to call when this
 * signal is emitted.  All observers get called before the
 * signal's "default action", if it has one.  Observers are
 * called on a first-come, first-served basis.
 * @param Event {Event type} an optional Event type to be used
 * for the returned Signal that defaults to Event.
 * @returns a Signal that is emitted before the given observer.
 */
self.addListener = // NodeJS
self.observe = Object.freeze(function (observer, Event) {
    var signal = Q.Signal(observer, Event);
    waiting.push(signal.emitter());
    return signal;
});

// XXX may be deprecated in the future in favor of a more secure or safe
// system for cancelling a signal.
self.removeListener = // NodeJS
self.dismiss = Object.freeze(function (observer) {
    var offset = waiting.indexOf(observer);
    if (offset < 0)
        return;
    waiting.splice(offset, 1);
});

/**
 * emits an event with to all observers and the signal's default action, by
 * applying each function with the event instance as the activation object
 * and the forwarding the given arguments.  Uses the event object to
 * determine whether to continue propagating from observer to the next, and
 * whether to apply the default action.
 */
self.emit = Object.freeze(function () {

    var event;
    if (this instanceof Event) {
        event = this;
    } else {
        event = Q.Event();
    }

    /* emit signals to observers with an Event as the activation
     * object. */
    for (var i = 0, ii = waiting.length; i < ii; i++) {
        var observer = waiting[i];
        if (!event.getPropagation())
            break;
        observer.apply(event, arguments);
    }

    /* call the "default" action function */
    if (action && event.getDefaulting()) {
        return action.apply(event, arguments);
    }

});

/**
 * @returns a function that, when called with
 * arbitrary arguments, arranges for the signal
 * to be observed with a given function that receives
 * those arguments.
 *
 * > var x = signal.observer(function (y, z) {
 * >     print("signal was observed with " + y + ", " + z);
 * > });
 * > x("a", 10);
 * > x("b", 20);
 * > x.emit();
 * signal was observed with a, 10
 * signal was observed with b, 20
 *
 */
self.observer = Object.freeze(function (observer, Event) {
    var that = this;
    return function () {
        var args = arguments;
        self.observe(function () {
            observer.apply(that, args);
        }, Event);
    };
});

/**
 * @returns {Function} a function that emits this signal when it is called.
 */
self.emitter = Object.freeze(function () {
    return Object.freeze(function () {
        return self.emit.apply(this, arguments);
    });
});

/**
 * @returns {Array} all observer functions in order.  Modifications to the
 * returned array will not affect the behavior of the signal.
 */
// required to implement NodeJS's promise.listeners()
self.getObservers = Object.freeze(function () {
    return Array.prototype.slice.call(waiting);
});

});

Object.freeze(Q.Signal);
Object.freeze(Q.Signal.prototype);

/** Emitter

• base prototype for objects with observable, named, event signals.
  */

Q.EventEmitter = // NodeJS
Q.Emitter = function () {
var self = Object.create(Q.Emitter.prototype);
Q.Emitter.constructor.call(this);
return Object.freeze(Object.create(self));
};

Q.Emitter.constructor = Object.freeze(function () {
var self = this;

var signals = {};

self.constructObservable = Object.freeze(function (observable) {
    observable.addListener = // NodeJS
    observable.observe = function (name, observer) {
        return self.getSignal(name).observe(observer);
    };
});

var observable = Object.create(Q.Observable.prototype);
self.constructObservable(observable);

self.observable = Object.freeze(Object.create(observable));

/**
 * emits an event to all observers of signal with a particular name.
 * Further arguments are applied to each observer.
 * @param name {String} the name of the signal to emit.
 */
self.emit = Object.freeze(function (name /* ...args */) {
    var args = Array.prototype.slice.call(arguments, 1);
    var signal = self.getSignal(name);
    return signal.emit.apply(signal, args);
});

/**
 * adds an observer to this object's signal for a given name.
 * @param name {String} the name of the signal to observe.
 */
self.addListener = // NodeJS
self.observe = Object.freeze(function (name, observer) {
    return self.getSignal(name).observe(observer);
});

/**
 * removes an observer from this object's signal for a given name.
 * @param name {String}
 * @param observer {Function}
 */
self.removeListener = // NodeJS
self.dismiss = Object.freeze(function (name, observer) {
    self.getSignal(name).dismiss(observer);
});

self.listeners = // NodeJS
self.getObservers = Object.freeze(function (name) {
    return self.getSignal(name).getObservers();
});

/**
 * adds a Signal slot to this event emitter with a given name.
 * @param name {String} the name of the signal slot.  Only one
 * signal can be created for each name.
 * @param signal an optional function or Signal object
 * @param Event an optional event type that will be instantiated and passed
 * as the activation object to each observer each time the signal emits an
 * event.
 * @returns a signal, albeit one wrapped around the given function.
 */
self.setSignal = Object.freeze(function (name, signal, Event) {
    if (!(signal instanceof Q.Signal))
        signal = Q.Signal(signal, Event);
    signals[name] = signal;
    return signal;
});

/**
 * returns the Signal for a given name.  Throws an error if
 * no signal has been slotted by the given name.
 * @param name {String} name of the signal to get.
 * @returns {Signal}
 */
self.getSignal = Object.freeze(function (name) {
    if (!Object.prototype.hasOwnProperty.call(signals, name))
        throw new Error("No such signal: " + name);
    return signals[name];
});

/**
 * @returns {boolean} whether a Signal has been registered for the given
 * name.
 */
self.hasSignal = Object.freeze(function (name) {
    return Object.prototype.hasOwnProperty.call(signals, name);
});

});

Object.freeze(Q.Emitter);
Object.freeze(Q.Emitter.prototype);

/** Observable < Emitter

• a mixin type for any object that can emit events when certain property
• functions are called.
  */

Q.Observable = function () {
var self = Object.create(Q.Observable.prototype);
Q.Observable.constructor.call(self);
return Object.freeze(Object.create(self));
};

Q.Observable.constructor = Object.freeze(function () {
var self = this;

Q.Emitter.constructor.call(self);

/**
 * sets a signal using the Emitter system, bypassing the Observable's
 * setSignal behavior of adding the emitter as a property of the instance.
 */
self.setSignalRaw = self.setSignal;

/**
 * adds a signal slot for the given name and sets it to a property of the
 * activation object (this).  This property function should only be called
 * during the process of constructing this instance.
 */
self.setSignal = Object.freeze(function (name, observer, Event) {
    var x;
    self[name] = x = self.setSignalRaw(name, observer, Event).emitter();
    if (x !== self[name])
    throw new Error("self[name] = failed silently");

});

// "observe" is observable.
self.setSignal("observe", function (name, observer) {
    return self.getSignal(name).observe(observer);
});

});

Q.Observable.prototype = Object.create(Q.Emitter.prototype);

Object.freeze(Q.Observable);
Object.freeze(Q.Observable.prototype);

// Deferred

/**

• a type of Deferred that corresponds to the future state of a
• value, including both the promise of for that value to be
• resolved, and a resolver which provides the means to advance the
• progress of the promise on its way to resolution.
  */

Q.Deferred = function (canceller) {
var self = Object.create(Q.Deferred.prototype);
Q.Deferred.constructor.call(self, canceller);
return Object.freeze(Object.create(self));
};

Q.Deferred.constructor = Object.freeze(function (canceller) {
var self = this;

Q.Observable.constructor.call(self);

var object; // a Promise, either a Reference, Resolution, or Rejection
var waiting = []; // all pending emissions (emit argument arrays)
var progress;

// The Promise for a Deferred must close on the Deferred's
// internal state.
/**
 * the promise to be eventually resolved.
 */
var promise = Object.create(Q.Promise.prototype);

Q.Promise.constructor.call(promise, canceller);

/**
 * a Deferred's promise differs from a normal event Emitter
 * because it has two states: "waiting" and "resolved".  When
 * the promise is waiting, all event emissions are queued.  When
 * the promise is either resolved or rejected, all of those
 * events are emitted.  All subsequent emissions are sent
 * immediately.
 */
promise.setSignal("emit", Object.freeze(function (operator, block /* ...args */) {
    if (waiting)
        waiting.push(Array.prototype.slice.call(arguments));
    else
        object.emit.apply(object, arguments);
}));

/**
 * @returns either a promise or the resolved value for the promise.
 */
promise.setSignal("valueOf", Object.freeze(function () { // ref_send ("near")
    if (waiting)
        return promise;
    if (typeof object === "object" && object !== null)
        return object.valueOf();
    return object;
}));

promise.setSignal("progress", Object.freeze(function (_progress) {
    progress = _progress;
}));

promise.getProgress = function () {
    return progress;
};

self.promise = Object.freeze(Object.create(promise));

/**
 * resolves the promise or defers it further with a new promise.
 */
self.emitSuccess = // Node
self.callback = // Dojo
self.resolve = Object.freeze(function (resolution) { // ref_send
    if (!waiting)
        return;
    var todo = waiting;
    waiting = undefined;
    object = Q.promise(resolution);
    for (var i = 0, ii = todo.length; i < ii; i++) {
        object.emit.apply(object, todo[i]);
    }
});

/**
 * rejects the promise by resolving it with a Rejection with 
 * a given "reason"
 * @param reason {Error}
 */
self.reject = Object.freeze(function (reason) {
    self.resolve(Q.Rejection(reason));
});

/**
 * forwards the "when" message to the contained promise to
 * emulate the promise API.
 */
self.setSignal("when", function (ok, error, progress) {
    return Q.when(self.promise, ok, error, progress);
});

/**
 * a signal that can be called to set the progress state
 * of the deferrence to a number between 0 and 1, or can
 * be observed with the "observe" method.
 * @param progress {Number} between 0 and 1 inclusive.
 */
self.setSignal("progress", function (_progress) {
    self.promise.progress(_progress);
});

/**
 * @returns the progress of the deferred or undefined if that is unknown.
 * User interface widgets should take "undefined" as a queue to display
 * indefinite progress.
 */
self.getProgress = Object.freeze(function () {
    return progress;
});

/** ok
 * a signal that can be observed but not explicitly emitted for when the
 * promise is fully resolved.
 */

/** error
 * a signal that can be observed but not explicitly emitted for when the
 * promise is rejected.
 */

// these are special, since they in turn have to call Q.when,
// which would cause an infinite loop if it were observed while
// constructing an observer
self.observe("observe", function (name, observer) {
    if (name == "ok") {
        Q.when(self.promise, observer);
        this.stop();
    } else if (name == "error") {
        Q.when(self.promise, undefined, observer);
        this.stop();
    } else if (name == "progress") {
        Q.when(self.promise, undefined, undefined, observer);
        this.stop();
    }
});


/** cancel
 * a signal that rejects the promise and notifies any observers.
 */
self.setSignal("cancel", function () { // NodeJS
    self.promise.cancel();
});

});

Object.freeze(Q.Deferred);

/**

• @param time {Number} in miliseconds, at which point the corresponding

• promise will be rejected if it has not been resolved.
  */
  Q.Deferred.prototype.timeout = Object.freeze(function (time) { // NodeJS
  var self = this;

  if (!Q.setTimeout)
  throw new Error("Timers are not supported by this engine.");

  var timeout = Q.setTimeout(function () {
  self.promise.reject(new Error("timeout"));
  }, time);

  var cancelTimeout = function () {
  Q.clearTimeout(timeout);
  };

  Q.when(self.promise, cancelTimeout, cancelTimeout);

});

// Promise-like Emulation
Q.Deferred.prototype.then = function () {
var promise = this.promise;
return promise.then.apply(promise, arguments);
};

// NodeJS
Q.Deferred.prototype.emitError = Object.freeze(function () {
this.reject.apply(this, arguments);
});

// Dojo
Q.Deferred.prototype.errback = Object.freeze(function () {
this.reject.apply(this, arguments);
});

// Dojo
Q.Deferred.prototype.addCallback = Object.freeze(function (observer) {
Q.when(this.promise, observer);
return this;
});

// Dojo
Q.Deferred.prototype.addErrback = Object.freeze(function (observer) {
Q.when(this.promise, undefined, observer);
return this;
});

// Dojo
Q.Deferred.prototype.addBoth = Object.freeze(function (callback, errback) {
Q.when(this.promise, callback, errback);
return this;
});

Q.Deferred.prototype.toSource =
Q.Deferred.prototype.toString = Object.freeze(function () {
return "[object Deferred]";
});

Object.freeze(Q.Deferred.prototype);

/**

• An object that represents a promise to provide a value eventually. When
• this value is provided or fails to be provided can be observed using
• "Q.when(promise, ok, error, progress)".
  */
  // Promise < Observable < Emitter of ok, error, progress but only
  // once.
  // the canceller is a byproduct of Dojo
  Q.Promise = function (canceller) {
  var self = Object.create(Q.Promise.prototype);
  Q.Promise.constructor.call(self);
  return Object.freeze(Object.create(self));
  };

Q.Promise.constructor = Object.freeze(function (canceller) {
var self = this;

Q.Observable.constructor.call(self); // super-constructor

// override emit
self.emit = Object.freeze(function (operator /* ...args */) {
    var method = self[operator] || Object.freeze(function () {
        if (!self.noSuchMethod)
            throw new Error("Promise did not provide requisite noSuchMethod method");
        return self.noSuchMethod.apply(
            self,
            [operator].concat(
                Array.prototype.slice.call(arguments)
            )
        );
    });
    var args = Array.prototype.slice.call(arguments, 1);
    Q.enqueue(function () {
        method.apply(self, args);
    });
});

/**
 * blocks until this promise has been resolved or rejected, if the
 * underlying engine supports blocking promises.
 */
self.wait = Object.freeze(function () {
    return Q.wait(self);
});

self.observe("observe", function (name, observer) {
    if (name === "ok") {
        Q.when(self, observer);
        this.stop();
    } else if (name === "error") {
        Q.when(self, undefined, observer);
        this.stop();
    } else if (name == "progress") {
        Q.when(self, undefined, undefined, observer);
        this.stop();
    }
});

/**
 * a signal that rejects this promise with a cancellation error, or the
 * given error and notifies all observers.  Observers are afforded an
 * opportunity to prevent cancellation through their event object.
 */
// Dojo + NodeJS
self.setSignal("cancel", function (error) {
    if (canceller) // Dojo
        error = canceller();
    if (!(error instanceof Error))
        error = new Error(error); // TODO CanceledError
    // NodeJS's behavior of depleting the "waiting" queue is
    // implicit to the "ref_send" model of forwarding all
    // emissions to the "Reference" promise.
    self.reject(error);
});

});

Q.Promise.prototype = Object.create(Q.Emitter.prototype);

Object.freeze(Q.Promise);

// -- kriszyp Kris Zyp
Q.Promise.prototype.then = Object.freeze(function () {
Q.when.apply(Q, [this].concat(Array.prototype.slice.call(arguments)));
});

/**

• rejects Promise API calls that are not supported by this type of promise.
  */
  Q.Promise.prototype.noSuchMethod = Object.freeze(function () {
  return Q.Rejection("No such method");
  });

Q.Promise.prototype.toSource =
Q.Promise.prototype.toString = Object.freeze(function () {
return "[object Promise]";
});

// NodeJS emitSuccess, emitError, and emitCancel omitted for
// securability reasons. Use a Deferred for these.

// NodeJS, Dojo (on a Deferred)
Q.Promise.prototype.addCallback = Object.freeze(function (observer) {
this.observe("ok", observer);
return this;
});

// NodeJS, Dojo (on a Deferred)
Q.Promise.prototype.addErrback = Object.freeze(function (observer) {
this.observe("error", observer);
return this;
});

// Dojo (on a Deferred)
Q.Promise.prototype.addBoth = Object.freeze(function (callback, errback) {
this.observe("ok", callback);
this.observe("error", errback);
return this;
});

// NodeJS
Q.Promise.prototype.addCancelback = Object.freeze(function (cancelback) {
this.observe("cancel", cancelback);
return this;
});

Object.freeze(Q.Promise.prototype);

/**

• A type of Promise that represents rejection of a promise for some given
• reason.
  */

Q.Rejection = function (reason) {
var self = Object.create(Q.Rejection.prototype);
Q.Rejection.constructor.call(self, reason);
return Object.create(self);
};

Q.Rejection.constructor = Object.freeze(function (reason) {
var self = this;
Q.Promise.constructor.call(self);
self.setSignal("when", function (ok, error, progress) {
if (progress)
Q.enqueue(function () {
progress(0);
});
return error ? error(Q.Rejection(reason)) : Q.Rejection(reason);
});
});

Q.Rejection.prototype = Object.create(Q.Promise.prototype);

Object.freeze(Q.Rejection);

Q.Rejection.prototype.toSource =
Q.Rejection.prototype.toString = Object.freeze(function () {
return "[object Rejection]";
});

Object.freeze(Q.Rejection.prototype);

/**

• A type of Promise that represents a value on its way to resolution.
  */

Q.Reference = function (object) {
var self = Object.create(Q.Reference.prototype);
Q.Reference.constructor.call(self, object);
return Object.freeze(Object.create(self));
};

Q.Reference.constructor = Object.freeze(function (object) {
var self = this;

Q.Promise.constructor.call(self);

if (typeof object === "number" && !isFinite(object))
    return Q.Rejection("NaN");

self.setSignal("valueOf", function () {
    return object;
});

self.setSignal("when", function (ok, error, progress) {
    if (progress)
        Q.enqueue(function () {
            progress(1);
        });
    return ok ? ok(object) : object;
});

self.setSignal("get", function (block, name) {
    var result = name === undefined ? object : object[name];
    return block ? block(result) : result;
});

self.setSignal("post", function (block, name, args) {
    if (name === undefined)
        return Q.Rejection("A name must be supplied");
    var result = object[name].apply(object, args);
    return block ? block(result) : result;
});

self.setSignal("put", function (block, name, value) {
    if (name === undefined)
        return Q.Rejection("A name must be supplied");
    object[name] = value;
    return block ? block(value) : value;
});

self.setSignal("del", function (block, name) {
    delete object[name];
    return block ? block(value) : value;
});

});

Q.Reference.prototype = Object.create(Q.Promise.prototype);

// ref_send alias
Q.Reference.prototype.near = function () {
return this.valueOf.apply(this, arguments);
};

Object.freeze(Q.Reference);
Object.freeze(Q.Reference.prototype);

/** Q API

• Promise manager to make it easier to consume and produce
• promises.
  */

/**

• returns a Deferred. A future is an Emitter and contains
• a promise and its corresponding resolver.
  */
  Q.defer = Object.freeze(function () {
  return Q.Deferred();
  });

/**

• given any value, a reference promise, a resolved promise, or a
• rejected promise, return a promise. If the given object is not a
• promise, it will be wrapped as a reference promise.
  */
  Q.promise = Object.freeze(function (object) {
  if (Q.isPromise(object)) {
  return object;
  } else {
  return Q.Reference(object);
  }
  });

/**

• returns whether a given object is recognized
• as a promise. Presently, this amounts to duck-typing
• on the presence of a "then" property function, but
• could conceivably be done by checking whether the object
• is an instance of Promise.
• @param object
• @returns whether the given object is a promise.
  */
  Q.isPromise = Object.freeze(function (object) {
  return (object && typeof object.then === "function") ||
  object instanceof Q.Promise // covers Rejections
  });

/**

• returns a Reference.
• @param value
  */
  Q.ref = Object.freeze(function (value) {
  return Q.Reference(value);
  });

/**

• given any value, a reference promise, a resolved promise, or a
• rejected promise, attempt to return the most resolved form of the
• value. If the promise is resolved, this will be a non-promise
• object.
  */
  Q.valueOf = Object.freeze(function (object) {
  if (Q.isPromise(object))
  return object.valueOf();
  return object;
  });

/**

• returns a Rejection
• @param reason {Error}
  */
  Q.reject = Object.freeze(function (reason) {
  return Q.Rejection(reason);
  });

/**

• Registers an observer on a promise.
• @param value promise or value to observe
• @param resolvedCallback function to be called with the resolved value
• @param rejectCallback function to be called with the rejection reason
• @param progressCallback function to be called when progress is made
• @return promise for the return value from the invoked callback or the value if it
• is a non-promise value
  */
  Q.when = Object.freeze(function (value, ok, error, progress) {
  if(Q.isPromise(value)){
  return Q.whenPromise(value, ok, error, progress);
  }
  return ok(value);
  });

/**

• Registers an observer on a promise.

• @param value promise or value to observe

• @param resolvedCallback function to be called with the resolved value

• @param rejectCallback function to be called with the rejection reason

• @param progressCallback function to be called when progress is made

• @return promise for the return value from the invoked callback
  */
  Q.whenPromise = Object.freeze(function (value, ok, error, progress) {
  var deferred = Q.Deferred();
  var done = false; // ensure the untrusted promise
  // makes at most a single call to one of the callbacks

  Q.promise(value).emit("when", function (value) {
  if (done)
  throw new Error("Already observed"); // XXX
  done = true;
  deferred.resolve(Q.Reference(value).when(ok, error, progress));
  }, function (reason) {
  if (done)
  throw new Error("Already observed"); // XXX
  done = true;
  deferred.resolve(Q.Rejection(reason).when(ok, error, progress));
  }, deferred.progress);

  return deferred.promise;
  });

/**

• Gets the value of a property in a future turn.
• @param target promise or value for target object
• @param property name of property to get
• @return promise for the property value
  */
  Q.get = Object.freeze(function (object, name) {
  var deferred = Q.defer();
  Q.promise(object).get(deferred.resolve, name);
  return deferred.promise;
  });

/**

• Sets the value of a property in a future turn.
• @param target promise or value for target object
• @param property name of property to set
• @param value new value of property
• @return promise for the return value
  */
  Q.put = Object.freeze(function (object, name, value) {
  Q.promise(object).put(deferred.resolve, name, value);
  });

/**

• Invokes a method in a future turn.
• @param target promise or value for target object
• @param methodName name of method to invoke
• @param args array of invocation arguments
• @return promise for the return value
  */
  Q.post = Object.freeze(function (object, name, args) {
  var deferred = Q.defer();
  Q.promise(object).post(deferred.resolve, name, args);
  return deferred.promise;
  });

Q.del = Object.freeze(function (object, name) {
var deferred = Q.defer();
Q.promise(object).del(deferred.resolve, name);
});

/**

• Waits for the given promise to finish, blocking (and executing
• other events) if necessary to wait for the promise to finish. If
• target is not a promise it will return the target immediately. If
• the promise results in an rejection, that rejection will be
• thrown.
• @param object promise or value to wait for
• @return the value of the promise
  */
  Q.wait = Object.freeze(function (object) {
  if (!queue)
  throw new Error("Can not wait, the event-queue module is not available");
  if (object && Q.isPromise(object)) {
  var done, error, result;
  Q.when(object, function (value) {
  done = true;
  result = value;
  }, function (reason) {
  done = true;
  error = reason;
  });
  while (!done)
  queue.processNextEvent(true);
  if (error)
  throw error;
  return result;
  } else {
  return object;
  }
  });

Object.freeze(exports);