diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..05a4010 --- /dev/null +++ b/LICENSE @@ -0,0 +1,23 @@ +Copyright 2009, 2010, 2011 Isaac Z. Schlueter. +All rights reserved. + +Permission is hereby granted, free of charge, to any person +obtaining a copy of this software and associated documentation +files (the "Software"), to deal in the Software without +restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index ed0905f..59ad738 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,143 @@ -# Slide - a tiny flow control library +# Controlling Flow: callbacks are easy -Callbacks are simple and easy if you keep the pattern consistent. +## What's actually hard? -Check out the [slide presentation](http://github.com/isaacs/slide-flow-control/raw/master/nodejs-controlling-flow.pdf). +- Doing a bunch of things in a specific order. +- Knowing when stuff is done. +- Handling failures. +- Breaking up functionality into parts (avoid nested inline callbacks) -You'll laugh when you see how little code is actually in this thing. -It's so not-enterprisey, you won't believe it. It does almost nothing, -but it's super handy. -I actually use an earlier version of this util in -[a real world program](http://npmjs.org/). +## Common Mistakes -## Installation +- Abandoning convention and consistency. +- Putting all callbacks inline. +- Using libraries without grokking them. +- Trying to make async code look sync. -Just copy the files into your project, and use them that way, or -you can do this: +## Define Conventions - npm install slide +- Two kinds of functions: *actors* take action, *callbacks* get results. +- Essentially the continuation pattern. Resulting code *looks* similar + to fibers, but is *much* simpler to implement. +- Node works this way in the lowlevel APIs already, and it's very flexible. -and then: +## Callbacks - var asyncMap = require("slide").asyncMap - , chain = require("slide").chain - // use the power! +- Simple responders +- Must always be prepared to handle errors, that's why it's the first argument. +- Often inline anonymous, but not always. +- Can trap and call other callbacks with modified data, or pass errors upwards. -Enjoy! +## Actors + +- Last argument is a callback. +- If any error occurs, and can't be handled, pass it to the callback and return. +- Must not throw. Return value ignored. +- return x ==> return cb(null, x) +- throw er ==> return cb(er) + +```javascript +// return true if a path is either +// a symlink or a directory. +function isLinkOrDir (path, cb) { + fs.lstat(path, function (er, s) { + if (er) return cb(er) + return cb(null, s.isDirectory() || s.isSymbolicLink()) + }) +} +``` + +# asyncMap + +## Usecases + +- I have a list of 10 files, and need to read all of them, and then continue when they're all done. +- I have a dozen URLs, and need to fetch them all, and then continue when they're all done. +- I have 4 connected users, and need to send a message to all of them, and then continue when that's done. +- I have a list of n things, and I need to dosomething with all of them, in parallel, and get the results once they're all complete. + + +## Solution + +```javascript +var asyncMap = require("slide").asyncMap +function writeFiles (files, what, cb) { + asyncMap(files, function (f, cb) { + fs.writeFile(f, what, cb) + }, cb) +} +writeFiles([my, file, list], "foo", cb) +``` + +# chain + +## Usecases + +- I have to do a bunch of things, in order. Get db credentials out of a file, + read the data from the db, write that data to another file. +- If anything fails, do not continue. +- I still have to provide an array of functions, which is a lot of boilerplate, + and a pita if your functions take args like + +```javascript +function (cb) { + blah(a, b, c, cb) +} +``` + +- Results are discarded, which is a bit lame. +- No way to branch. + +## Solution + +- reduces boilerplate by converting an array of [fn, args] to an actor + that takes no arguments (except cb) +- A bit like Function#bind, but tailored for our use-case. +- bindActor(obj, "method", a, b, c) +- bindActor(fn, a, b, c) +- bindActor(obj, fn, a, b, c) +- branching, skipping over falsey arguments + +```javascript +chain([ + doThing && [thing, a, b, c] +, isFoo && [doFoo, "foo"] +, subChain && [chain, [one, two]] +], cb) +``` + +- tracking results: results are stored in an optional array passed as argument, + last result is always in results[results.length - 1]. +- treat chain.first and chain.last as placeholders for the first/last + result up until that point. + + +## Non-trivial example + +- Read number files in a directory +- Add the results together +- Ping a web service with the result +- Write the response to a file +- Delete the number files + +```javascript +var chain = require("slide").chain +function myProgram (cb) { + var res = [], last = chain.last, first = chain.first + chain([ + [fs, "readdir", "the-directory"] + , [readFiles, "the-directory", last] + , [sum, last] + , [ping, "POST", "example.com", 80, "/foo", last] + , [fs, "writeFile", "result.txt", last] + , [rmFiles, "./the-directory", first] + ], res, cb) +} +``` + +# Conclusion: Convention Profits + +- Consistent API from top to bottom. +- Sneak in at any point to inject functionality. Testable, reusable, ... +- When ruby and python users whine, you can smile condescendingly. diff --git a/package.json b/package.json index 5cc2689..f037db6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "slide", - "version": "1.1.3", + "version": "1.1.4", "author": "Isaac Z. Schlueter (http://blog.izs.me/)", "contributors": [ "S. Sriram (http://www.565labs.com)"