Add pattern examples #18
Conversation
Start work on adding pattern examples.
I'd love some feedback about this - it's adapted from the bluebird wiki. It might sound too argumentative?
| @@ -0,0 +1,46 @@ | |||
| ##The Explicit Construction Anti-Pattern | |||
There was a problem hiding this comment.
Some hash or double? It is not consistent with the other file. Also, there should be a space after the hash for readability right?
|
+1. I love the idea of documenting knowledge like this. |
| - __rejected__ meaning that the computation failed. | ||
|
|
||
| Promise returning functions _should never throw_, they should return rejections instead. | ||
| Throwing from a promise returning function will force you to use both a `} catch { ` _and_ a `.catch`. |
There was a problem hiding this comment.
An example here would be very helpful.
| }); | ||
| ``` | ||
|
|
||
| ###How do I work with the API in promises, how do I "promisify" it? |
There was a problem hiding this comment.
Might need a space between # and H here.
|
A few naming nits: Do you mind changing |
|
(Also, this is excellent work! Thank you for PR'ing it.) |
|
Sure, I'll address the comments tomorrow or later tonight. I'm fine with renaming to examples. |
| @@ -0,0 +1,84 @@ | |||
| # The Promise Disposer Pattern | |||
There was a problem hiding this comment.
Is this really a pattern? Can you provide some sources? (articles, examples of code, etc)
There was a problem hiding this comment.
Well, yes. It's pretty common, I've given two examples of popular libraries using it - I can find more if you'd like. There is also general stuff like http://promise-nuggets.github.io/articles/21-context-managers-transactions.html and more.
There was a problem hiding this comment.
The pattern accomplishes same things as python's with, C#'s using, Java's try-with-resources, C++'s RAII. Here's a example http://promise-nuggets.github.io/articles/21-context-managers-transactions.html
There was a problem hiding this comment.
Well, you've linked to issues that were opened by you, so it might look like something that you are promoting
There was a problem hiding this comment.
Oh thanks, I copied most of this content here from StackOverflow. I opened those two (and indeed both libraries use the pattern now) but I can gladly link to other libraries I had nothing to do with that happen to use the pattern. It's pretty common and the reason I linked to it from the StackOverflow post is that it includes the debate which I thought was interesting.
There was a problem hiding this comment.
@benjamingr, @petkaantonov I would not compare it with RAII though, its too different. The others are specifically designed for managing non-memory resources in a garbage collected language where RAII isn't available anymore.
@vkurchatkin its true, we introduced this feature in bluebird and I haven't seen other libraries adopt it. I guess most people consider it trivial as its simplest implementation can be easily written with .finally().
I'd say its effective difference from finally is non-trivial though, because returning disposers lets API authors ensure that a resource cannot be used in any other way other than by passing it in a using closure. And doing that guarantees that regardless of whether the block was successful, or any exceptions or errors happened, it will call the resource's disposer when done. Finally it also provides the one important place where node really does need to crash: if the code that releases (scarce) resources throws or asynchronously fails.
There was a problem hiding this comment.
I see, this is not an established pattern and it probably shouldn't be here?
There was a problem hiding this comment.
Its not established in JavaScript in the sense that I haven't seen another library provide it out of the box. Bluebird users are using it.
I would say its an established pattern in other languages, since they've added special official keywords for it (C# using keyword, Python with keyword, Java try-with-resources). And AFAIK, they are all based on the finally part of try-catch-finally in the same way that this pattern is.
So to be honest, while its technically not "established", its obviousness and equivalency to finally-based patterns I think earns its keep. If thats not enough, we could remove it.
There was a problem hiding this comment.
I would say its an established pattern in other languages
we are talking specifically about promise-based patterns. finally is already a part of javascript
There was a problem hiding this comment.
finally is not analogous to any of those synchronous patterns (those languages even contain separate finally statement), especially when promises are concerned since it's very easy to cause leaks when using finally to cleanup parallel promises (this is a strong motivator for the using method in bluebird in the first place)
Start work on adding pattern examples.
I will post here examples of many common promise patterns, idioms and anti patterns.