{"_id":"vargs-callback","_rev":"13-48203dc6bda0db4167fcb48048b6c514","name":"vargs-callback","description":"Variable arguments and \"The last is the callback\" convention made without \"var args = somehowParse(arguments)\" surrogate.","dist-tags":{"latest":"0.2.3"},"versions":{"0.1.0":{"name":"vargs-callback","version":"0.1.0","description":"Variable arguments and \"The last is the callback\" convention made without \"var args = somehowParse(arguments)\" surrogate.","main":"index.js","scripts":{"test":"make test"},"repository":{"type":"git","url":"git://github.com/furagu/vargs-callback.git"},"keywords":["function","variable","arguments","argument","callback","varg","vargs"],"author":{"name":"Egor Balyshev"},"license":{"type":"MIT","url":"https://raw.github.com/furagu/vargs-callback/master/LICENSE"},"bugs":{"url":"https://github.com/furagu/vargs-callback/issues"},"devDependencies":{"should":"~2.1.0","mocha":"~1.15.1"},"readme":"# vargs-callback\n \n## The Problem\n \nDealing with variable function arguments makes you write some uncool boilerplate of this sort:\n \n```js\nfunction openTheDoor(door, options, callback) {\n    if (typeof options === 'function') {\n        callback = options\n        options = {}\n    }\n    // actual function code using parameters\n    if (door.isOpen) return\n    // ...\n}\n```\n\nThis juggling is actually not what you want your function to do, this is just a workaround of JavaScript function arguments implementation. There should be a way to do variable arguments clearly.\n\n## Bad Solutions\n\nThere are some libraries providing the solution by processing arguments object. It ends up with another boilerplate like this:\n \n```js\nfunction openTheDoor() {\n    var args = somehowParse(arguments)\n    // actual function code using args object\n    // note there are no argument names \n    if (args.first.isOpen) return \n    // ...\n}\n```\n \nOr with little \"arguments definition language\":\n \n```js\nfunction openTheDoor() {\n    var args = parseArgs(['door|obj', 'options||obj', 'callback||func'], arguments)\n    // actual function code using args object\n    if (args.door.isOpen) return\n    // ...\n}\n```\n\nSome do weird call-twice-to-set-parameters magic which forces you to cast a spell involving ```this``` and write your actuial code inside a callback:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    return magic(this, ['door|obj', 'options||obj', 'callback||func'], function () {\n        // actual function code using parameters\n        // note the callback around and the return statement at the beginning\n        if (door.isOpen) return\n        // ...\n    })\n}\n```\n\nThe common problem of all that solutions is that you basically replace one boilerplate with another. Yes, you can not only load arguments, but also check types, you can even set default values. But still this is a boilerplate cluttering your code.\n\n## The Solution\n\nLet's talk about functions.\n\nFirst, a well-designed function should not have many parameters. Having more than three parameters often means function needs refactoring. One should split the code to several different funcitons, aggregate some separate parameters into one parameter object, so there are only small and concise functions left ([Refactoring: Improving the Design of Existing Code](http://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672) by Martin Fowler is the book to read on the subject).\n\nSecond, there is a simple native way to deal with missing parameters. If there are less arguments than stated in the function parameter list, missing parameters take ```undefined``` value. One could do something like ```options = options || {}``` to handle such cases. It is natural, simple and easy to read.\n\nFinally, there is the \"Callback goes last\" convention which simplifies asynchronous programming. This convention creates situations in which the callback takes place of one of the optional parameters. Callback taking the wrong place is the root cause of the variable arguments problem.\n\nStated thus, the solution comes easily. The only thing needs to be done is _to move the callback to its place_, leaving missing parameters undefined. This is exactly what vargs-callback does.\n\n## Usage\n\nThe library exports only one function and adds one non-enumerable property ```vargs``` to Function.prototype. Use it as follows.\n\nGlobal or named functions:\n\n```js\nvar vargs = require('vargs-callback')\n\nfunction openTheDoor(door, options, callback) {\n    // actual function code using parameters\n    if (door.isOpen) return\n    // ...\n}\nopenTheDoor = vargs(openTheDoor) // Decorate named/global function\n```\n\nObject methods:\n\n```js\nvar vargs = require('vargs-callback')\n\nvar doorOpener = {\n open: function (door, options, callback) {\n        // actual function code using parameters\n        if (door.isOpen) return\n        // ...\n    }.vargs // Decorate anonymous function with accessor property. Note the absence of ()\n    //...\n}\n```\n\n## The Rules\n\nVargs decorator works on the original function call and does exactly the following:\n\n1.  If there are not enough arguments given and the last given argument is a function, insert ```undefined``` values into original arguments just before the last element to make it the same size as the original parameter list.\n2.  Call the original function with modified arguments.\n3.  Do not modify arguments if there are enough arguments or the last argument is not a function.\n","readmeFilename":"README.md","_id":"vargs-callback@0.1.0","dist":{"shasum":"6a30600333ffaf9560ea85533072017d7bd07e33","tarball":"http://registry.npmjs.org/vargs-callback/-/vargs-callback-0.1.0.tgz"},"_from":".","_npmVersion":"1.2.32","_npmUser":{"name":"furagu","email":"frag.trials@gmail.com"},"maintainers":[{"name":"furagu","email":"frag.trials@gmail.com"}]},"0.1.1":{"name":"vargs-callback","version":"0.1.1","description":"Variable arguments and \"The last is the callback\" convention made without \"var args = somehowParse(arguments)\" surrogate.","main":"index.js","scripts":{"test":"make test"},"repository":{"type":"git","url":"git://github.com/furagu/vargs-callback.git"},"keywords":["function","variable","arguments","argument","callback","varg","vargs"],"author":{"name":"Egor Balyshev"},"license":{"type":"MIT","url":"https://raw.github.com/furagu/vargs-callback/master/LICENSE"},"bugs":{"url":"https://github.com/furagu/vargs-callback/issues"},"devDependencies":{"should":"~2.1.0","mocha":"~1.15.1"},"readme":"# vargs-callback\n\n[Skip to usage](#Usage)\n\n## The Problem\n\nDealing with variable function arguments makes you write some uncool boilerplate of this sort:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    if (typeof options === 'function') {\n        callback = options\n        options = {}\n    }\n    // actual function code using parameters\n    if (door.isOpen) return\n    // ...\n}\n```\n\nThis juggling is actually not what you want your function to do, this is just a workaround of JavaScript function arguments implementation. There should be a way to do variable arguments clearly.\n\n## Bad Solutions\n\nThere are some libraries providing the solution by processing arguments object. It ends up with another boilerplate like this:\n\n```js\nfunction openTheDoor() {\n    var args = somehowParse(arguments)\n    // actual function code using args object\n    // note there are no argument names\n    if (args.first.isOpen) return\n    // ...\n}\n```\n\nOr with little \"arguments definition language\":\n\n```js\nfunction openTheDoor() {\n    var args = parseArgs(['door|obj', 'options||obj', 'callback||func'], arguments)\n    // actual function code using args object\n    if (args.door.isOpen) return\n    // ...\n}\n```\n\nSome do weird call-twice-to-set-parameters magic which forces you to cast a spell involving ```this``` and write your actuial code inside a callback:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    return magic(this, ['door|obj', 'options||obj', 'callback||func'], function () {\n        // actual function code using parameters\n        // note the callback around and the return statement at the beginning\n        if (door.isOpen) return\n        // ...\n    })\n}\n```\n\nThe common problem of all that solutions is that you basically replace one boilerplate with another. Yes, you can not only load arguments, but also check types, you can even set default values. But still this is a boilerplate cluttering your code.\n\n## Good Solution\n\nLet's talk about functions.\n\nFirst, a well-designed function should not have many parameters. Having more than three parameters often means function needs refactoring. One should split the code to several different funcitons, aggregate some separate parameters into one parameter object, so there are only small and concise functions left ([Refactoring: Improving the Design of Existing Code](http://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672) by Martin Fowler is the book to read on the subject).\n\nSecond, there is a simple native way to deal with missing parameters. If there are less arguments than stated in the function parameter list, missing parameters take ```undefined``` value. One could do something like ```options = options || {}``` to handle such cases. It is natural, simple and easy to read.\n\nFinally, there is the \"Callback goes last\" convention which simplifies asynchronous programming. This convention creates situations in which the callback takes place of one of the optional parameters. Callback taking the wrong place is the root cause of the variable arguments problem.\n\nStated thus, the solution comes easily. The only thing needs to be done is _to move the callback to its place_, leaving missing parameters undefined. This is exactly what vargs-callback does.\n\n<a name=\"Usage\" />\n## Usage\n\nThe library exports only one function and adds one non-enumerable property ```vargs``` to Function.prototype. Use it as follows.\n\nGlobal or named functions:\n\n```js\nvar vargs = require('vargs-callback')\n\nfunction openTheDoor(door, options, callback) {\n    // actual function code using parameters\n    // options will be undefined if only door and callback given\n    if (door.isOpen) return\n    // ...\n}\nopenTheDoor = vargs(openTheDoor) // Decorate named/global function\n```\n\nObject methods:\n\n```js\nvar vargs = require('vargs-callback')\n\nvar doorOpener = {\n open: function (door, options, callback) {\n        // actual function code using parameters\n        // options will be undefined if only door and callback given\n        if (door.isOpen) return\n        // ...\n    }.vargs // Decorate anonymous function with accessor property. Note the absence of ()\n    //...\n}\n```\n\n## The Rules\n\nVargs decorator works on the original function call and does exactly the following:\n\n1.  If there are not enough arguments given and the last given argument is a function, insert ```undefined``` values into original arguments just before the last element to make it the same size as the original parameter list.\n2.  Call the original function with modified arguments.\n3.  Do not modify arguments if there are enough arguments or the last argument is not a function.\n","readmeFilename":"README.md","_id":"vargs-callback@0.1.1","dist":{"shasum":"26f0b507b19f7854a8403f7e61606d95d2636046","tarball":"http://registry.npmjs.org/vargs-callback/-/vargs-callback-0.1.1.tgz"},"_from":".","_npmVersion":"1.2.32","_npmUser":{"name":"furagu","email":"frag.trials@gmail.com"},"maintainers":[{"name":"furagu","email":"frag.trials@gmail.com"}]},"0.2.0":{"name":"vargs-callback","version":"0.2.0","description":"Variable arguments and \"The last is the callback\" convention made without \"var args = somehowParse(arguments)\" surrogate.","main":"index.js","scripts":{"test":"make test"},"repository":{"type":"git","url":"git://github.com/furagu/vargs-callback.git"},"keywords":["function","variable","arguments","argument","callback","varg","vargs"],"author":{"name":"Egor Balyshev"},"license":{"type":"MIT","url":"https://raw.github.com/furagu/vargs-callback/master/LICENSE"},"bugs":{"url":"https://github.com/furagu/vargs-callback/issues"},"devDependencies":{"should":"~2.1.0","mocha":"~1.15.1"},"readme":"# vargs-callback\n\n[Skip to usage](#Usage)\n\n## The Problem\n\nDealing with variable function arguments makes you write some uncool boilerplate of this sort:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    if (typeof options === 'function') {\n        callback = options\n        options = {}\n    }\n    // actual function code using parameters\n    if (door.isOpen) return\n    // ...\n}\n```\n\nThis parameter juggling is not what you actually want your function to do, it's just a workaround of the JavaScript function arguments implementation.\nThere should be a way to get rid of it.\n\n## Bad Solutions\n\nThere are some libraries built to process the arguments object. It ends up with another boilerplate like this:\n\n```js\nfunction openTheDoor() {\n    var args = somehowParse(arguments)\n    // actual function code using args object\n    // note there are no argument names\n    if (args.first.isOpen) return\n    // ...\n}\n```\n\nSome provide a little \"arguments definition language\":\n\n```js\nfunction openTheDoor() {\n    var args = parseArgs(['door|obj', 'options||obj', 'callback||func'], arguments)\n    // actual function code using args object\n    if (args.door.isOpen) return\n    // ...\n}\n```\n\nSome do weird call-twice-to-set-parameters magic forcing you to cast a spell involving ```this``` and write your code inside a callback:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    return magicArgs(this, ['door|obj', 'options||obj', 'callback||func'], function () {\n        // actual function code using declared parameters\n        // note the callback around and the return statement at the beginning\n        if (door.isOpen) return\n        // ...\n    })\n}\n```\n\nA common problem of all these solutions is that you simply replace one boilerplate with another. You must still do some tricks before you can use the function parameters. And it clutters your code.\n\n## Good Solution\n\nLet's talk about functions.\n\nFirst, a well-designed function should not have many parameters. Having more than three parameters often means function needs refactoring. You should consider splitting the function code to several different funcitons or aggregating some of parameters into one parameter object until only small and concise functions left ([Refactoring: Improving the Design of Existing Code](http://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672) by Martin Fowler is the book to read on the subject).\n\nSecond, there is a native JavaScript way to deal with missing parameters. If there are not enough arguments missing parameters are set to ```undefined``` and you can do something like ```options = options || {}``` to handle such cases. It is natural, it is simple and easy to read.\n\nFinally, there is the \"Callback goes last\" convention which simplifies asynchronous programming. This convention creates situations when the callback takes place of one of the optional parameters. Callback taking the wrong place is the root cause of the variable arguments problem.\n\nCombining the above, the solution comes easily. The only thing needs to be done is _to move the callback to its place_, leaving missing parameters undefined. This is exactly what vargs-callback does.\n\n<a name=\"Usage\" />\n## Usage\n\nThe library exports only one function which should be used as a decorator.\n\nFunction declarations:\n\n```js\nvar vargs = require('vargs-callback')\n\nfunction openTheDoor(door, options, callback) {\n    // actual function code using parameters\n    // options will be undefined if only door and callback given\n    if (door.isOpen) return\n    // ...\n}\nopenTheDoor = vargs(openTheDoor) // Decorate global function\n```\n\nFunction expressions:\n\n```js\nvar vargs = require('vargs-callback')\n\nvar openTheDoor = vargs(function (door, options, callback) { // Decorate function expression\n    // actual function code using parameters\n    // options will be undefined if only door and callback given\n    if (door.isOpen) return\n    // ...\n})\n```\n\n## The Rules\n\nVargs is triggered on the decorated function call and does the following:\n\n1.  If there are not enough arguments given and the last given argument is a function, insert ```undefined``` values into arguments just before the last element to make arguments the same size as the declared function parameter list.\n2.  Call the original function with modified arguments.\n3.  Do not modify arguments if there are enough arguments or the last argument is not a function.\n","readmeFilename":"README.md","_id":"vargs-callback@0.2.0","dist":{"shasum":"91f98f6d4b32f5afe425b7fbb9b6bde7ab52bd9d","tarball":"http://registry.npmjs.org/vargs-callback/-/vargs-callback-0.2.0.tgz"},"_from":".","_npmVersion":"1.2.32","_npmUser":{"name":"furagu","email":"frag.trials@gmail.com"},"maintainers":[{"name":"furagu","email":"frag.trials@gmail.com"}]},"0.2.1":{"name":"vargs-callback","version":"0.2.1","description":"Variable arguments and \"The last is the callback\" convention made without \"var args = somehowParse(arguments)\" surrogate.","main":"index.js","scripts":{"test":"make test"},"repository":{"type":"git","url":"git://github.com/furagu/vargs-callback.git"},"keywords":["function","variable","arguments","argument","callback","varg","vargs"],"author":{"name":"Egor Balyshev"},"license":{"type":"MIT","url":"https://raw.github.com/furagu/vargs-callback/master/LICENSE"},"bugs":{"url":"https://github.com/furagu/vargs-callback/issues"},"devDependencies":{"should":"~2.1.0","mocha":"~1.15.1"},"readme":"# vargs-callback\n\n[Skip to usage](#Usage)\n\n## The Problem\n\nDealing with variable function arguments makes you write some uncool boilerplate of this sort:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    if (typeof options === 'function') {\n        callback = options\n        options = {}\n    }\n    // actual function code using parameters\n    if (door.isOpen) return\n    // ...\n}\n```\n\nThis parameter juggling is not what you actually want your function to do, it's just a workaround of the JavaScript function arguments implementation.\nThere should be a way to get rid of it.\n\n## Bad Solutions\n\nThere are some libraries built to process the arguments object. It ends up with another boilerplate like this:\n\n```js\nfunction openTheDoor() {\n    var args = somehowParse(arguments)\n    // actual function code using args object\n    // note there are no argument names\n    if (args.first.isOpen) return\n    // ...\n}\n```\n\nSome provide a little \"arguments definition language\":\n\n```js\nfunction openTheDoor() {\n    var args = parseArgs(['door|obj', 'options||obj', 'callback||func'], arguments)\n    // actual function code using args object\n    if (args.door.isOpen) return\n    // ...\n}\n```\n\nSome do weird call-twice-to-set-parameters magic forcing you to cast a spell involving ```this``` and write your code inside a callback:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    return magicArgs(this, ['door|obj', 'options||obj', 'callback||func'], function () {\n        // actual function code using declared parameters\n        // note the callback around and the return statement at the beginning\n        if (door.isOpen) return\n        // ...\n    })\n}\n```\n\nA common problem of all these solutions is that you simply replace one boilerplate with another. You must still do some tricks before you can use the function parameters. And it clutters your code.\n\n## Good Solution\n\nLet's talk about functions.\n\nFirst, a well-designed function should not have many parameters. Having more than three parameters often means function needs refactoring. You should consider splitting the function code to several different funcitons or aggregating some of parameters into one parameter object until only small and concise functions left ([Refactoring: Improving the Design of Existing Code](http://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672) by Martin Fowler is the book to read on the subject).\n\nSecond, there is a native JavaScript way to deal with missing parameters. All missing parameters are set to ```undefined``` and you can do something like ```options = options || {}``` to handle such cases. It is natural, it is simple and easy to read.\n\nFinally, there is the \"Callback goes last\" convention which simplifies asynchronous programming. This convention creates situations when the callback takes place of one of the optional parameters. Callback taking the wrong place is the root cause of the variable arguments problem.\n\nCombining the above, the solution comes easily. The only thing needs to be done is _to move the callback to its place_, leaving missing parameters undefined. This is exactly what vargs-callback does.\n\n<a name=\"Usage\" />\n## Usage\n\nThe library exports only one function which should be used as a decorator.\n\nFunction declarations:\n\n```js\nvar vargs = require('vargs-callback')\n\nfunction openTheDoor(door, options, callback) {\n    // actual function code using parameters\n    // options will be undefined if only door and callback given\n    if (door.isOpen) return\n    // ...\n}\nopenTheDoor = vargs(openTheDoor) // Decorate global function\n```\n\nFunction expressions:\n\n```js\nvar vargs = require('vargs-callback')\n\nvar openTheDoor = vargs(function (door, options, callback) { // Decorate function expression\n    // actual function code using parameters\n    // options will be undefined if only door and callback given\n    if (door.isOpen) return\n    // ...\n})\n```\n\n## The Rules\n\nVargs is triggered on the decorated function call and does the following:\n\n1.  If there are not enough arguments given and the last given argument is a function, insert ```undefined``` values into arguments just before the last element to make arguments the same size as the declared function parameter list.\n2.  Call the original function with modified arguments.\n3.  Do not modify arguments if there are enough arguments or the last argument is not a function.\n","readmeFilename":"README.md","_id":"vargs-callback@0.2.1","dist":{"shasum":"f6f7a9f263ee81a2370f6887f114c199bdf2cc3e","tarball":"http://registry.npmjs.org/vargs-callback/-/vargs-callback-0.2.1.tgz"},"_from":".","_npmVersion":"1.2.32","_npmUser":{"name":"furagu","email":"frag.trials@gmail.com"},"maintainers":[{"name":"furagu","email":"frag.trials@gmail.com"}]},"0.2.2":{"name":"vargs-callback","version":"0.2.2","description":"Variable arguments and \"The last is the callback\" convention made without \"var args = somehowParse(arguments)\" surrogate.","main":"index.js","scripts":{"test":"make test"},"repository":{"type":"git","url":"git://github.com/furagu/vargs-callback.git"},"keywords":["function","variable","arguments","argument","callback","varg","vargs"],"author":{"name":"Egor Balyshev"},"license":{"type":"MIT","url":"https://raw.github.com/furagu/vargs-callback/master/LICENSE"},"bugs":{"url":"https://github.com/furagu/vargs-callback/issues"},"devDependencies":{"should":"~2.1.0","mocha":"~1.15.1"},"readme":"# vargs-callback [![Build Status](https://travis-ci.org/furagu/vargs-callback.png?branch=master)](https://travis-ci.org/furagu/vargs-callback)\n\n[Skip to usage](#Usage)\n\n## The Problem\n\nDealing with variable function arguments makes you write some uncool boilerplate of this sort:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    if (typeof options === 'function') {\n        callback = options\n        options = {}\n    }\n    // actual function code using parameters\n    if (door.isOpen) return\n    // ...\n}\n```\n\nThis parameter juggling is not what you actually want your function to do, it's just a workaround of the JavaScript function arguments implementation.\nThere should be a way to get rid of it.\n\n## Bad Solutions\n\nThere are some libraries built to process the arguments object. It ends up with another boilerplate like this:\n\n```js\nfunction openTheDoor() {\n    var args = somehowParse(arguments)\n    // actual function code using args object\n    // note there are no argument names\n    if (args.first.isOpen) return\n    // ...\n}\n```\n\nSome provide a little \"arguments definition language\":\n\n```js\nfunction openTheDoor() {\n    var args = parseArgs(['door|obj', 'options||obj', 'callback||func'], arguments)\n    // actual function code using args object\n    if (args.door.isOpen) return\n    // ...\n}\n```\n\nSome do weird call-twice-to-set-parameters magic forcing you to cast a spell involving ```this``` and write your code inside a callback:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    return magicArgs(this, ['door|obj', 'options||obj', 'callback||func'], function () {\n        // actual function code using declared parameters\n        // note the callback around and the return statement at the beginning\n        if (door.isOpen) return\n        // ...\n    })\n}\n```\n\nA common problem of all these solutions is that you simply replace one boilerplate with another. You must still do some tricks before you can use the function parameters. And it clutters your code.\n\n## Good Solution\n\nLet's talk about functions.\n\nFirst, a well-designed function should not have many parameters. Having more than three parameters often means function needs refactoring. You should consider splitting the function code to several different funcitons or aggregating some of parameters into one parameter object until only small and concise functions left ([Refactoring: Improving the Design of Existing Code](http://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672) by Martin Fowler is the book to read on the subject).\n\nSecond, there is a native JavaScript way to deal with missing parameters. All missing parameters are set to ```undefined``` and you can do something like ```options = options || {}``` to handle such cases. It is natural, it is simple and easy to read.\n\nFinally, there is the \"Callback goes last\" convention which simplifies asynchronous programming. This convention creates situations when the callback takes place of one of the optional parameters. Callback taking the wrong place is the root cause of the variable arguments problem.\n\nCombining the above, the solution comes easily. The only thing needs to be done is _to move the callback to its place_, leaving missing parameters undefined. This is exactly what vargs-callback does.\n\n<a name=\"Usage\" />\n## Usage\n\nThe library exports only one function which should be used as a decorator.\n\nFunction declarations:\n\n```js\nvar vargs = require('vargs-callback')\n\nfunction openTheDoor(door, options, callback) {\n    // actual function code using parameters\n    // options will be undefined if only door and callback given\n    if (door.isOpen) return\n    // ...\n}\nopenTheDoor = vargs(openTheDoor) // Decorate global function\n```\n\nFunction expressions:\n\n```js\nvar vargs = require('vargs-callback')\n\nvar openTheDoor = vargs(function (door, options, callback) { // Decorate function expression\n    // actual function code using parameters\n    // options will be undefined if only door and callback given\n    if (door.isOpen) return\n    // ...\n})\n```\n\n## The Rules\n\nVargs is triggered on the decorated function call and does the following:\n\n1.  If there are not enough arguments given and the last given argument is a function, insert ```undefined``` values into arguments just before the last element to make arguments the same size as the declared function parameter list.\n2.  Call the original function with modified arguments.\n3.  Do not modify arguments if there are enough arguments or the last argument is not a function.\n","readmeFilename":"README.md","_id":"vargs-callback@0.2.2","dist":{"shasum":"bccf1252f57f276f35d54baeb39d6f9b803956c6","tarball":"http://registry.npmjs.org/vargs-callback/-/vargs-callback-0.2.2.tgz"},"_from":".","_npmVersion":"1.2.32","_npmUser":{"name":"furagu","email":"frag.trials@gmail.com"},"maintainers":[{"name":"furagu","email":"frag.trials@gmail.com"}]},"0.2.3":{"name":"vargs-callback","version":"0.2.3","description":"Variable arguments and \"The last is the callback\" convention made without \"var args = somehowParse(arguments)\" surrogate.","main":"index.js","scripts":{"test":"make test"},"repository":{"type":"git","url":"git://github.com/furagu/vargs-callback.git"},"keywords":["function","variable","arguments","argument","callback","varg","vargs"],"author":{"name":"Egor Balyshev"},"license":{"type":"MIT","url":"https://raw.github.com/furagu/vargs-callback/master/LICENSE"},"bugs":{"url":"https://github.com/furagu/vargs-callback/issues"},"devDependencies":{"should":"~2.1.0","mocha":"~1.15.1","benchmark":"~1.0.0"},"readme":"# vargs-callback [![Build Status](https://travis-ci.org/furagu/vargs-callback.png?branch=master)](https://travis-ci.org/furagu/vargs-callback)\n\n[Skip to usage](#Usage)\n\n## The Problem\n\nDealing with variable function arguments makes you write some uncool boilerplate of this sort:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    if (typeof options === 'function') {\n        callback = options\n        options = {}\n    }\n    // actual function code using parameters\n    if (door.isOpen) return\n    // ...\n}\n```\n\nThis parameter juggling is not what you actually want your function to do, it's just a workaround of the JavaScript function arguments implementation.\nThere should be a way to get rid of it.\n\n## Bad Solutions\n\nThere are some libraries built to process the arguments object. It ends up with another boilerplate like this:\n\n```js\nfunction openTheDoor() {\n    var args = somehowParse(arguments)\n    // actual function code using args object\n    // note there are no argument names\n    if (args.first.isOpen) return\n    // ...\n}\n```\n\nSome provide a little \"arguments definition language\":\n\n```js\nfunction openTheDoor() {\n    var args = parseArgs(['door|obj', 'options||obj', 'callback||func'], arguments)\n    // actual function code using args object\n    if (args.door.isOpen) return\n    // ...\n}\n```\n\nSome do weird call-twice-to-set-parameters magic forcing you to cast a spell involving ```this``` and write your code inside a callback:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    return magicArgs(this, ['door|obj', 'options||obj', 'callback||func'], function () {\n        // actual function code using declared parameters\n        // note the callback around and the return statement at the beginning\n        if (door.isOpen) return\n        // ...\n    })\n}\n```\n\nA common problem of all these solutions is that you simply replace one boilerplate with another. You must still do some tricks before you can use the function parameters. And it clutters your code.\n\n## Good Solution\n\nLet's talk about functions.\n\nFirst, a well-designed function should not have many parameters. Having more than three parameters often means function needs refactoring. You should consider splitting the function code to several different funcitons or aggregating some of parameters into one parameter object until only small and concise functions left ([Refactoring: Improving the Design of Existing Code](http://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672) by Martin Fowler is the book to read on the subject).\n\nSecond, there is a native JavaScript way to deal with missing parameters. All missing parameters are set to ```undefined``` and you can do something like ```options = options || {}``` to handle such cases. It is natural, it is simple and easy to read.\n\nFinally, there is the \"Callback goes last\" convention which simplifies asynchronous programming. This convention creates situations when the callback takes place of one of the optional parameters. Callback taking the wrong place is the root cause of the variable arguments problem.\n\nCombining the above, the solution comes easily. The only thing needs to be done is _to move the callback to its place_, leaving missing parameters undefined. This is exactly what vargs-callback does.\n\n<a name=\"Usage\" />\n## Usage\n\nThe library exports only one function which should be used as a decorator.\n\nFunction declarations:\n\n```js\nvar vargs = require('vargs-callback')\n\nfunction openTheDoor(door, options, callback) {\n    // actual function code using parameters\n    // options will be undefined if only door and callback given\n    if (door.isOpen) return\n    // ...\n}\nopenTheDoor = vargs(openTheDoor) // Decorate global function\n```\n\nFunction expressions:\n\n```js\nvar vargs = require('vargs-callback')\n\nvar openTheDoor = vargs(function (door, options, callback) { // Decorate function expression\n    // actual function code using parameters\n    // options will be undefined if only door and callback given\n    if (door.isOpen) return\n    // ...\n})\n```\n\n## The Rules\n\nVargs is triggered on the decorated function call and does the following:\n\n1.  If there are not enough arguments given and the last given argument is a function, insert ```undefined``` values into arguments just before the last element to make arguments the same size as the declared function parameter list.\n2.  Call the original function with modified arguments.\n3.  Do not modify arguments if there are enough arguments or the last argument is not a function.\n","readmeFilename":"README.md","_id":"vargs-callback@0.2.3","dist":{"shasum":"5d92e6f4d51c7f087da8e8aea70535d01ca5a2c2","tarball":"http://registry.npmjs.org/vargs-callback/-/vargs-callback-0.2.3.tgz"},"_from":".","_npmVersion":"1.2.32","_npmUser":{"name":"furagu","email":"frag.trials@gmail.com"},"maintainers":[{"name":"furagu","email":"frag.trials@gmail.com"}]}},"readme":"# vargs-callback\n \n## The Problem\n \nDealing with variable function arguments makes you write some uncool boilerplate of this sort:\n \n```js\nfunction openTheDoor(door, options, callback) {\n    if (typeof options === 'function') {\n        callback = options\n        options = {}\n    }\n    // actual function code using parameters\n    if (door.isOpen) return\n    // ...\n}\n```\n\nThis juggling is actually not what you want your function to do, this is just a workaround of JavaScript function arguments implementation. There should be a way to do variable arguments clearly.\n\n## Bad Solutions\n\nThere are some libraries providing the solution by processing arguments object. It ends up with another boilerplate like this:\n \n```js\nfunction openTheDoor() {\n    var args = somehowParse(arguments)\n    // actual function code using args object\n    // note there are no argument names \n    if (args.first.isOpen) return \n    // ...\n}\n```\n \nOr with little \"arguments definition language\":\n \n```js\nfunction openTheDoor() {\n    var args = parseArgs(['door|obj', 'options||obj', 'callback||func'], arguments)\n    // actual function code using args object\n    if (args.door.isOpen) return\n    // ...\n}\n```\n\nSome do weird call-twice-to-set-parameters magic which forces you to cast a spell involving ```this``` and write your actuial code inside a callback:\n\n```js\nfunction openTheDoor(door, options, callback) {\n    return magic(this, ['door|obj', 'options||obj', 'callback||func'], function () {\n        // actual function code using parameters\n        // note the callback around and the return statement at the beginning\n        if (door.isOpen) return\n        // ...\n    })\n}\n```\n\nThe common problem of all that solutions is that you basically replace one boilerplate with another. Yes, you can not only load arguments, but also check types, you can even set default values. But still this is a boilerplate cluttering your code.\n\n## The Solution\n\nLet's talk about functions.\n\nFirst, a well-designed function should not have many parameters. Having more than three parameters often means function needs refactoring. One should split the code to several different funcitons, aggregate some separate parameters into one parameter object, so there are only small and concise functions left ([Refactoring: Improving the Design of Existing Code](http://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672) by Martin Fowler is the book to read on the subject).\n\nSecond, there is a simple native way to deal with missing parameters. If there are less arguments than stated in the function parameter list, missing parameters take ```undefined``` value. One could do something like ```options = options || {}``` to handle such cases. It is natural, simple and easy to read.\n\nFinally, there is the \"Callback goes last\" convention which simplifies asynchronous programming. This convention creates situations in which the callback takes place of one of the optional parameters. Callback taking the wrong place is the root cause of the variable arguments problem.\n\nStated thus, the solution comes easily. The only thing needs to be done is _to move the callback to its place_, leaving missing parameters undefined. This is exactly what vargs-callback does.\n\n## Usage\n\nThe library exports only one function and adds one non-enumerable property ```vargs``` to Function.prototype. Use it as follows.\n\nGlobal or named functions:\n\n```js\nvar vargs = require('vargs-callback')\n\nfunction openTheDoor(door, options, callback) {\n    // actual function code using parameters\n    if (door.isOpen) return\n    // ...\n}\nopenTheDoor = vargs(openTheDoor) // Decorate named/global function\n```\n\nObject methods:\n\n```js\nvar vargs = require('vargs-callback')\n\nvar doorOpener = {\n open: function (door, options, callback) {\n        // actual function code using parameters\n        if (door.isOpen) return\n        // ...\n    }.vargs // Decorate anonymous function with accessor property. Note the absence of ()\n    //...\n}\n```\n\n## The Rules\n\nVargs decorator works on the original function call and does exactly the following:\n\n1.  If there are not enough arguments given and the last given argument is a function, insert ```undefined``` values into original arguments just before the last element to make it the same size as the original parameter list.\n2.  Call the original function with modified arguments.\n3.  Do not modify arguments if there are enough arguments or the last argument is not a function.\n","maintainers":[{"name":"furagu","email":"frag.trials@gmail.com"}],"time":{"modified":"2013-12-11T15:14:30.465Z","created":"2013-12-08T10:21:20.512Z","0.1.0":"2013-12-08T10:21:25.536Z","0.1.1":"2013-12-08T10:38:13.544Z","0.2.0":"2013-12-09T15:55:24.914Z","0.2.1":"2013-12-10T04:31:56.393Z","0.2.2":"2013-12-10T13:32:12.552Z","0.2.3":"2013-12-11T15:14:30.465Z"},"author":{"name":"Egor Balyshev"},"repository":{"type":"git","url":"git://github.com/furagu/vargs-callback.git"}}