fluture - npm Package Compare versions

Comparing version 10.1.1 to 10.2.0

package.json

 {
   "name": "fluture",
-  "version": "10.1.1",
+  "version": "10.2.0",
   "description": "FantasyLand compliant (monadic) alternative to Promises",
@@ -60,3 +60,2 @@ "main": "index",
     "concurrify": "^1.1.1",
-    "denque": "^1.1.1",
     "sanctuary-show": "^1.0.0",
@@ -80,3 +79,3 @@ "sanctuary-type-identifiers": "^2.0.0"
     "ramda": "^0.25.0",
-    "remark-cli": "^5.0.0",
+    "remark-cli": "^6.0.0",
     "remark-validate-links": "^7.1.0",
@@ -83,0 +82,0 @@ "rimraf": "^2.6.2",

README.md

@@ -5,17 +5,13 @@ # [![Fluture](logo.png)](#butterfly)
 [![Code Coverage][]](https://codecov.io/gh/fluture-js/Fluture/branch/master)
-[![Greenkeeper Enabled][]](https://greenkeeper.io)
 [![Dependency Status][]](https://david-dm.org/fluture-js/Fluture)
-[![NPM Releases][]](https://www.npmjs.com/package/fluture?activeTab=versions)
-[![NPM Downloads][]](https://www.npmjs.com/package/fluture)
+[![NPM Package][]](https://www.npmjs.com/package/fluture)
 [![Gitter Chat][]](https://gitter.im/fluture-js/Fluture)
-[![StackOverflow Questions][]](https://stackoverflow.com/questions/tagged/fluture)
+[![Questions and Answers][]](https://stackoverflow.com/questions/tagged/fluture)
 
 [Build Status]: https://img.shields.io/travis/fluture-js/Fluture/master.svg
 [Code Coverage]: https://img.shields.io/codecov/c/github/fluture-js/Fluture/master.svg
-[Greenkeeper Enabled]: https://badges.greenkeeper.io/fluture-js/Fluture.svg
 [Dependency Status]: https://img.shields.io/david/fluture-js/Fluture.svg
-[NPM Releases]: https://img.shields.io/npm/v/fluture.svg
-[NPM Downloads]: https://img.shields.io/npm/dm/fluture.svg
-[Gitter Chat]: https://img.shields.io/gitter/room/fluture-js/Fluture.svg
-[StackOverflow Questions]: https://img.shields.io/stackexchange/stackoverflow/t/fluture.svg
+[NPM Package]: https://img.shields.io/npm/v/fluture.svg
+[Gitter Chat]: https://img.shields.io/gitter/room/fluture-js/Fluture.svg?colorB=blue
+[Questions and Answers]: https://img.shields.io/stackexchange/stackoverflow/t/fluture.svg?label=questions
 
@@ -35,3 +31,3 @@ Fluture offers a control structure similar to Promises, Tasks, Deferreds, and
 * [Integration](#sanctuary) with [Sanctuary][S].
-* A pleasant debugging experience through informative error messages.
+* [A pleasant debugging experience](#debugging).
 
@@ -140,2 +136,3 @@ For more information:
 - [On stack safety](#stack-safety)
+- [Debugging with Fluture](#debugging)
 - [Usage with Sanctuary](#sanctuary)
@@ -218,5 +215,11 @@ - [Using multiple versions of Fluture](#casting-futures)
 
-<details><summary>Resource management and utilities</summary>
+<details><summary>Resource management</summary>
 
 - [`hook`: Safely create and dispose resources](#hook)
+- [`finally`: Run a Future after the previous settles](#finally)
+
+</details>
+
+<details><summary>Other utilities</summary>
+
 - [`pipe`: Apply a function to a Future in a fluent method chain](#pipe)
@@ -226,2 +229,4 @@ - [`cache`: Cache a Future so that it can be forked multiple times](#cache)
 - [`never`: A Future that never settles](#never)
+- [`debugMode`: Configure Fluture's debug mode](#debugmode)
+- [`context`: The debugging context of a Future instance](#context)
 
@@ -292,2 +297,5 @@ </details>
 - **Catchable e f** - A function `f` which may throw an exception `e`.
+- **List** - Fluture's internal linked-list structure: `{ head :: Any, tail :: List }`.
+- **Context** - Fluture's internal debugging context object:
+  `{ tag :: String, name :: String, stack :: String }`.
 
@@ -392,2 +400,40 @@ #### Type classes
 
+### Debugging
+
+First and foremost, Fluture type-checks all of its input and throws TypeErrors
+when incorrect input is provided. The messages they carry are designed to
+provide enough insight to figure out what went wrong.
+
+Secondly, Fluture catches exceptions that are thrown asynchronously, and
+exposes them to you in one of two ways:
+
+1. By throwing an Error when it happens.
+2. By calling your [exception handler](#forkcatch) with an Error.
+
+The original exception isn't used because it might have been any value.
+Instead, a regular JavaScript Error instance whose properties are based on the
+original exception is created. Its properties are as follows:
+
+- `name`: Always just `"Error"`.
+- `message`: The original error message, or a message describing the value.
+- `reason`: The original value that was caught by Fluture.
+- `context`: A linked list of "context" objects. This is used to create the
+  `stack` property, and you generally don't need to look at it. If debug mode
+  is not enabled, the list is always empty.
+- `stack`: The stack trace of the original exception if it had one, or the
+  Error's own stack trace otherwise. If debug mode (see below) is enabled,
+  additional stack traces from the steps leading up to the crash are included.
+- `future`: The instance of [`Future`](#future) that was being
+  [consumed](#consuming-futures) when the exception happened. Often printing it
+  as a String can yield useful information. You can also try to consume it in
+  isolation to better identify what's going wrong.
+
+Finally, as mentioned, Fluture has a [debug mode](#debugmode) wherein
+additional contextual information across multiple JavaScript ticks is
+collected, included as an extended "async stack trace" on Errors, and
+[exposed on Future instances](#context).
+
+Debug mode can have a significant impact on performance, and uses up memory,
+so I would advise against using it in production.
+
 ### Sanctuary
@@ -1242,7 +1288,9 @@
 
+See [Debugging](#debugging) for information about the Error object that is
+recovered.
+
 ```js
 var fut = Future.after(300, null).map(x => x.foo);
 fut.forkCatch(console.error, console.error, console.log);
-//! Error: TypeError occurred while running a computation for a Future:
-//!   Cannot read property 'foo' of null
+//! Cannot read property 'foo' of null
 ```
@@ -1775,2 +1823,45 @@
 
+#### debugMode
+
+<details><summary><code>debugMode :: Boolean -> Undefined</code></summary>
+
+```hs
+debugMode :: Boolean -> Undefined
+```
+
+</details>
+
+Enable or disable Fluture's debug mode. Debug mode is disabled by default.
+Pass `true` to enable, or `false` to disable.
+
+```js
+Future.debugMode(true);
+```
+
+For more information, see [Debugging](#debugging) and [Context](#context).
+
+#### context
+
+```hs
+context :: Future a b ~> List Context
+```
+
+A linked list of debugging contexts made available on every instance of
+`Future`. When [debug mode](#debugmode) is disabled, the list is always empty.
+
+The context objects have `stack` properties which contain snapshots of the
+stacktraces leading up to the creation of the `Future` instance. They are used
+by Fluture to generate asynchronous stack traces.
+
+```js
+Future.debugMode(true);
+const future = Future.after(10, 'Hello');
+
+let context = future.context;
+while(context.head){
+  console.log(context.head.stack);
+  context = context.tail;
+}
+```
+
 ## License
@@ -1777,0 +1868,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

232757

increased by8.46%

Dependency count

3

decreased by-25%

Number of package files

57

increased by1.79%

Lines of code

4449

increased by8.22%

Number of lines in readme file

1907

increased by5.01%

Dependency changes

• - Removeddenque@^1.1.1

• - Removeddenque@1.5.1(transitive)