Sage/streamlinejs — pull request #180 by aseemk (2013-12-07 15:24:16+00:00)
Title: Improvements to explicit future error messaging

The current explicit future message makes sense given the implementation:

```
Error: invalid argument #1: you must pass _ or !_ (https://github.com/Sage/streamlinejs/issues/164)
```

But after playing with this and writing up some [best practices](https://gist.github.com/aseemk/7818408), I've realized that this message is misleading:

- The calling code doesn't have to be in Streamline. If it's not, `_` and `!_` don't mean anything to the developer encountering this message. This is particularly significant if you write a module for public consumption (as I do).

- But even if you're calling from your own Streamline code, it's actually not the case that `_` and `!_` are the only two options; you can still pass a regular callback, if you want to run the function async'ly but still handle errors.

So I improved the error message to something regular JS developers would understand, and added (and linked to from the error message) an FAQ entry that dives into detail for Streamline users:

```
Error: no callback given (argument #x). If you're a Streamline user, more info: https://github.com/Sage/streamlinejs/blob/master/FAQ.md#no-callback-given-error
```

You can view the FAQ entry here:

https://github.com/aseemk/streamlinejs/blob/explicit-futures-error-improvements/FAQ.md#no-callback-given-error

All browser tests from `dev.html` pass, but I'm not sure if those tests cover explicit futures.

Hope you find this a valuable change!

==

I'd have loved to make two further improvements, but I didn't know how best to achieve them.

1. If a user encounters this error, they need to see what function they're calling, and from where, so they can fix it. But the current stack trace begins with an internal Streamline function, so that info doesn't stick out.

```
at __func (/path/to/streamline-code.js:2:2475)
at theStreamlineFunc__4 [as theStreamlineFunc] (/path/to/streamline-code.js:170:14)
at theCallingFunc (/path/to/calling-code.js:174:4)
...
```

Is it possible to strip that first line from the stack trace?

2. Not a huge deal, but it'd be great if this error case could detect whether the calling code was in Streamline, and only include the FAQ link in the error message if it was.

One way to detect that would be to inspect the stack trace and look for `._js` / `._coffee`, but (a) I don't know if that's portable across environments and engines, and (b) that wouldn't work if the calling Streamline code was compiled to JS first. Any thoughts or suggestions?

Thanks Bruno!