ts-promise - npm Package Compare versions

Comparing version 0.2.1 to 0.2.2

dist/lib/Promise.d.ts

@@ -7,2 +7,29 @@ import Trace from "./Trace";
 /**
+ * A ts-promise implements the 'synchronous inspection' interface which allows
+ * to synchronously determine the promise's current state.
+ */
+export interface Inspection<T> {
+    /**
+    * @return `true` when promise is fulfilled, `false` otherwise.
+    */
+    isFulfilled(): boolean;
+    /**
+    * @return `true` when promise is rejected, `false` otherwise.
+    */
+    isRejected(): boolean;
+    /**
+    * @return `true` when promise is pending (may be resolved to another pending
+    *         promise), `false` otherwise.
+    */
+    isPending(): boolean;
+    /**
+    * @return Fulfillment value if fulfilled, otherwise throws an error.
+    */
+    value(): T;
+    /**
+    * @return Rejection reason if rejected, otherwise throws an error.
+    */
+    reason(): any;
+}
+/**
  * Thrown when a rejected promise is explicitly terminated with `.done()`.
@@ -89,3 +116,3 @@ */
  */
-export declare class Promise<T> implements Thenable<T> {
+export declare class Promise<T> implements Thenable<T>, Inspection<T> {
     private _id;
@@ -214,2 +241,31 @@ private _state;
     /**
+     * Asynchronous equivalent of try { } finally { }.
+     *
+     * Runs `handler` when promise resolves (fulfilled or rejected).
+     * Handler is passed the current promise (which is guaranteed to be
+     * resolved), and can be interrogated with e.g. `isFulfilled()`, `.value()`,
+     * etc.
+     *
+     * When `handler` returns `undefined` or its promise is fulfilled, the
+     * promise from `finally()` is resolved to the original promise's resolved
+     * value or rejection reason.
+     * If `handler` throws an error or returns a rejection, the result of
+     * `finally()` will be rejected with that error.
+     *
+     * Example:
+     * someLenghtyOperation().finally((result) => {
+     *   if (result.isFulfilled()) {
+     *     console.log("succeeded");
+     *   } else {
+     *     console.log("failed", result.reason());
+     *   }
+     * });
+     *
+     * @param  handler [description]
+     * @return promise with same value/reason as this one, after `handler`'s
+     *         result (if any) has been fulfilled, or a promise rejected with
+     *         `handler`'s error if it threw one or returned a rejection.
+     */
+    finally(handler: (result: Promise<T>) => void | Thenable<void>): Promise<T>;
+    /**
      * @return `true` when promise is fulfilled, `false` otherwise.
@@ -216,0 +272,0 @@ */

dist/lib/Promise.js

@@ -36,8 +36,9 @@ /**
         // thrown, than where it was thrown inside the promise lib.
-        if (this.reason && typeof this.reason === "object") {
-            var stack = this.reason.stack;
-            if (typeof stack === "string") {
-                this.stack = "UnhandledRejectionError: " + stack;
-            }
+        // In case we don't have a stack, explicitly state so, to not let people
+        // chase a problem in the promise lib that isn't there...
+        var stack = this.reason && typeof this.reason === "object" && this.reason.stack;
+        if (typeof stack !== "string") {
+            stack = String(reason);
         }
+        this.stack = "UnhandledRejectionError: " + stack;
     }
@@ -275,2 +276,35 @@ return UnhandledRejectionError;
     /**
+     * Asynchronous equivalent of try { } finally { }.
+     *
+     * Runs `handler` when promise resolves (fulfilled or rejected).
+     * Handler is passed the current promise (which is guaranteed to be
+     * resolved), and can be interrogated with e.g. `isFulfilled()`, `.value()`,
+     * etc.
+     *
+     * When `handler` returns `undefined` or its promise is fulfilled, the
+     * promise from `finally()` is resolved to the original promise's resolved
+     * value or rejection reason.
+     * If `handler` throws an error or returns a rejection, the result of
+     * `finally()` will be rejected with that error.
+     *
+     * Example:
+     * someLenghtyOperation().finally((result) => {
+     *   if (result.isFulfilled()) {
+     *     console.log("succeeded");
+     *   } else {
+     *     console.log("failed", result.reason());
+     *   }
+     * });
+     *
+     * @param  handler [description]
+     * @return promise with same value/reason as this one, after `handler`'s
+     *         result (if any) has been fulfilled, or a promise rejected with
+     *         `handler`'s error if it threw one or returned a rejection.
+     */
+    Promise.prototype.finally = function (handler) {
+        var _this = this;
+        var runner = function () { return handler(_this); };
+        return this.then(runner, runner).return(this);
+    };
+    /**
      * @return `true` when promise is fulfilled, `false` otherwise.
@@ -661,6 +695,9 @@ */
             var originalStack = this._result.stack;
-            Object.defineProperty(this._result, "stack", {
-                enumerable: false,
-                get: function () { return originalStack + "\n  from Promise at:\n" + _this._trace.inspect(); }
-            });
+            // Stack may be undefined if e.g. a Stack Overflow occurred
+            if (originalStack) {
+                Object.defineProperty(this._result, "stack", {
+                    enumerable: false,
+                    get: function () { return originalStack + "\n  from Promise at:\n" + _this._trace.inspect(); }
+                });
+            }
         }
@@ -667,0 +704,0 @@ this._flush();

dist/ts-promise.d.ts

@@ -87,2 +87,29 @@ declare module 'ts-promise/util' {
 	/**
+	 * A ts-promise implements the 'synchronous inspection' interface which allows
+	 * to synchronously determine the promise's current state.
+	 */
+	export interface Inspection<T> {
+		/**
+		* @return `true` when promise is fulfilled, `false` otherwise.
+		*/
+		isFulfilled(): boolean;
+		/**
+		* @return `true` when promise is rejected, `false` otherwise.
+		*/
+		isRejected(): boolean;
+		/**
+		* @return `true` when promise is pending (may be resolved to another pending
+		*		 promise), `false` otherwise.
+		*/
+		isPending(): boolean;
+		/**
+		* @return Fulfillment value if fulfilled, otherwise throws an error.
+		*/
+		value(): T;
+		/**
+		* @return Rejection reason if rejected, otherwise throws an error.
+		*/
+		reason(): any;
+	}
+	/**
 	 * Thrown when a rejected promise is explicitly terminated with `.done()`.
@@ -169,3 +196,3 @@ */
 	 */
-	export class Promise<T> implements Thenable<T> {
+	export class Promise<T> implements Thenable<T>, Inspection<T> {
 		private _id;
@@ -294,2 +321,31 @@ private _state;
 		/**
+		 * Asynchronous equivalent of try { } finally { }.
+		 *
+		 * Runs `handler` when promise resolves (fulfilled or rejected).
+		 * Handler is passed the current promise (which is guaranteed to be
+		 * resolved), and can be interrogated with e.g. `isFulfilled()`, `.value()`,
+		 * etc.
+		 *
+		 * When `handler` returns `undefined` or its promise is fulfilled, the
+		 * promise from `finally()` is resolved to the original promise's resolved
+		 * value or rejection reason.
+		 * If `handler` throws an error or returns a rejection, the result of
+		 * `finally()` will be rejected with that error.
+		 *
+		 * Example:
+		 * someLenghtyOperation().finally((result) => {
+		 *   if (result.isFulfilled()) {
+		 *	 console.log("succeeded");
+		 *   } else {
+		 *	 console.log("failed", result.reason());
+		 *   }
+		 * });
+		 *
+		 * @param  handler [description]
+		 * @return promise with same value/reason as this one, after `handler`'s
+		 *		 result (if any) has been fulfilled, or a promise rejected with
+		 *		 `handler`'s error if it threw one or returned a rejection.
+		 */
+		finally(handler: (result: Promise<T>) => void | Thenable<void>): Promise<T>;
+		/**
 		 * @return `true` when promise is fulfilled, `false` otherwise.
@@ -296,0 +352,0 @@ */

package.json

 {
   "name": "ts-promise",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Fast, robust, type-safe promises",
@@ -5,0 +5,0 @@ "author": "Martin Poelstra <[e-mail]>",

README.md

@@ -106,3 +106,4 @@ <a href="https://promisesaplus.com/">
 
-Solid documentation is still on the TODO.
+All public methods and interfaces have JSDoc comments, so if your favorite IDE
+supports these, you'll have instant inline documentation.
 
@@ -112,2 +113,4 @@ That said, the library's interface should be very unsurprising: basically ES6
 
+For your convenience, here's a list of what's available on Promise.
+
 Static methods on Promise:
@@ -188,2 +191,21 @@ - `constructor(resolver: (resolve: (value: T | Thenable<T>) => void, reject: (reason: Error) => void) => void)`
   the error through Node's `uncaughtException`, or when running in a browser.
+- `finally(handler: (result: Promise<T>) => void|Thenable<void>): Promise<T>`
+  Asynchronous equivalent of try { } finally { }.
+  Runs `handler` when promise resolves (fulfilled or rejected).
+  Handler is passed the current promise (which is guaranteed to be
+  resolved), and can be interrogated with e.g. `isFulfilled()`, `.value()`,
+  etc.
+  When `handler` returns `undefined` or its promise is fulfilled, the
+  promise from `finally()` is resolved to the original promise's resolved
+  value or rejection reason.
+  If `handler` throws an error or returns a rejection, the result of
+  `finally()` will be rejected with that error.
+  Example:
+      someLenghtyOperation().finally((result) => {
+          if (result.isFulfilled()) {
+              console.log("succeeded");
+          } else {
+              console.log("failed", result.reason());
+          }
+      });
 - `isFulfilled(): boolean`
@@ -259,2 +281,7 @@ Returns true when promise is fulfilled, false otherwise.
 
+0.2.2 (2015-08-04):
+- Implement `.finally()` (#3)
+- Add `Inspection<T>` interface (#4)
+- Don't confuse users by showing our internal stack trace when Node didn't provide one for UnhandledRejectionError
+
 0.2.1 (2015-06-24):
@@ -261,0 +288,0 @@ - Improve stack trace for UnhandledRejectionError

src/lib/Promise.ts

@@ -25,2 +25,34 @@ /**
 /**
+ * A ts-promise implements the 'synchronous inspection' interface which allows
+ * to synchronously determine the promise's current state.
+ */
+export interface Inspection<T> {
+	/**
+	* @return `true` when promise is fulfilled, `false` otherwise.
+	*/
+	isFulfilled(): boolean;
+
+	/**
+	* @return `true` when promise is rejected, `false` otherwise.
+	*/
+	isRejected(): boolean;
+
+	/**
+	* @return `true` when promise is pending (may be resolved to another pending
+	*         promise), `false` otherwise.
+	*/
+	isPending(): boolean;
+
+	/**
+	* @return Fulfillment value if fulfilled, otherwise throws an error.
+	*/
+	value(): T;
+
+	/**
+	* @return Rejection reason if rejected, otherwise throws an error.
+	*/
+	reason(): any;
+}
+
+/**
  * Thrown when a rejected promise is explicitly terminated with `.done()`.
@@ -48,8 +80,9 @@ */
 		// thrown, than where it was thrown inside the promise lib.
-		if (this.reason && typeof this.reason === "object") {
-			let stack = this.reason.stack;
-			if (typeof stack === "string") {
-				this.stack = "UnhandledRejectionError: " + stack;
-			}
+		// In case we don't have a stack, explicitly state so, to not let people
+		// chase a problem in the promise lib that isn't there...
+		let stack = this.reason && typeof this.reason === "object" && this.reason.stack;
+		if (typeof stack !== "string") {
+			stack = String(reason);
 		}
+		this.stack = "UnhandledRejectionError: " + stack;
 	}
@@ -196,3 +229,3 @@ }
  */
-export class Promise<T> implements Thenable<T> {
+export class Promise<T> implements Thenable<T>, Inspection<T> {
 	private _id = promiseIdCounter++;
@@ -476,2 +509,35 @@ private _state: State = State.Pending;
 	/**
+	 * Asynchronous equivalent of try { } finally { }.
+	 *
+	 * Runs `handler` when promise resolves (fulfilled or rejected).
+	 * Handler is passed the current promise (which is guaranteed to be
+	 * resolved), and can be interrogated with e.g. `isFulfilled()`, `.value()`,
+	 * etc.
+	 *
+	 * When `handler` returns `undefined` or its promise is fulfilled, the
+	 * promise from `finally()` is resolved to the original promise's resolved
+	 * value or rejection reason.
+	 * If `handler` throws an error or returns a rejection, the result of
+	 * `finally()` will be rejected with that error.
+	 *
+	 * Example:
+	 * someLenghtyOperation().finally((result) => {
+	 *   if (result.isFulfilled()) {
+	 *     console.log("succeeded");
+	 *   } else {
+	 *     console.log("failed", result.reason());
+	 *   }
+	 * });
+	 *
+	 * @param  handler [description]
+	 * @return promise with same value/reason as this one, after `handler`'s
+	 *         result (if any) has been fulfilled, or a promise rejected with
+	 *         `handler`'s error if it threw one or returned a rejection.
+	 */
+	public finally(handler: (result: Promise<T>) => void|Thenable<void>): Promise<T> {
+		let runner = () => handler(this);
+		return this.then(runner, runner).return(this);
+	}
+
+	/**
 	 * @return `true` when promise is fulfilled, `false` otherwise.
@@ -979,6 +1045,9 @@ */
 			var originalStack = this._result.stack;
-			Object.defineProperty(this._result, "stack", {
-				enumerable: false,
-				get: (): string => originalStack + "\n  from Promise at:\n" + this._trace.inspect()
-			});
+			// Stack may be undefined if e.g. a Stack Overflow occurred
+			if (originalStack) {
+				Object.defineProperty(this._result, "stack", {
+					enumerable: false,
+					get: (): string => originalStack + "\n  from Promise at:\n" + this._trace.inspect()
+				});
+			}
 		}
@@ -985,0 +1054,0 @@ this._flush();

No alert changes

Improved metrics

Total package byte prevSize

993907

increased by9.89%

Number of package files

64

increased by4.92%

Lines of code

6353

increased by32.66%

Number of lines in readme file

329

increased by8.94%

No dependency changes