{"dist":{"shasum":"2652026abe5ec751b745d9c9fcf56fa82b82dd99","tarball":"https://registry.npmjs.org/make-sync/-/make-sync-0.1.3.tgz","integrity":"sha512-sMSqQ8/tdN5c+d3e38ueUbXVm3gQ0rw/0YWVstSTeasvahC1kpYp7LjTj4JdgumCPxJW//KIJ+mnAXcBS6pazg==","signatures":[{"sig":"MEUCIQCdFnRlWLt/7ccahQrfzg244dHNr785tZBv0gFpAQk5jQIgAJ0VihR7/JdeNN08HEvyX38SIb0m29PwNtuZ3Q6NfG8=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}]},"main":"./index","name":"make-sync","_from":".","author":{"name":"Seb Vincent","email":"seb.vincent@gmail.com"},"engine":"node >= 0.6.1","readme":"# make-sync [![Build Status](https://secure.travis-ci.org/sebv/node-make-sync.png?branch=master)](http://travis-ci.org/sebv/node-make-sync)\n\n\nThis module uses  [node-fibers](http://github.com/laverdet/node-fibers) to transform asynchronous functions into \nsynchronous ones. This is designed to work with asynchronous functions following the standard ('done' callback \nas the last arg).\n\nThe main commands are:\n\n*   MakeSync to synchronize a function or object.\n*   Sync to start a sync environment (starts a fiber).\n\nWhen applied to an object, MakeSync patches all the object methods by default. \nIt is also possible to pass some options to be more specific.\n\nThe following modes may be used to to make function synchronous (see description\nfurther down):\n   - sync (default)\n   - async\n   - mixed-args (default 'mixed')\n   - mixed-fibers\n\n\n## install\n\n```\nnpm install make-sync\n```\n\n\n## usage (coffeescript)\n\n### simple example\n\n```coffeescript\n{Sync, MakeSync} = require 'make-sync'\n\nf = (a,b,done) ->\n  res = a+b\n  done null, res\n\n# making synchronous \nf = MakeSync f\n\n# sync call\nSync ->\n  res = f 1, 2\n  console.log \"sync ->\", res \n\nobj = \n  f: (a,b,done) ->\n    res = a+b\n    done null, res\n\n# making synchronous\nMakeSync obj\n\n# sync call  \nSync ->\n  res = obj.f 1, 2\n  console.log \"obj sync ->\", res   \n```\n\n\n## modes\n\n### sync (default)\n\n```coffeescript\nf = MakeSync f\n# or\nf = MakeSync f, mode:'sync'\n```\n\nThis mode assumes that the function is always called in sync mode within a \nfiber, so that the 'done' callback is never there. (ie if there is a function\nat the end it will assume this is a function argument and add it own callback)\n\n\n### async\n\n```coffeescript\nf = MakeSync f, mode:'async'\n```\n\nThis mode assumes that the function is always called in asynchronous mode, \nso doesn't change the function behavior. (probably not useful in most case)  \n\n\n### mixed-args (default mixed)\n\n```coffeescript\nf = MakeSync f, mode:'mixed'\n# or\nf = MakeSync f, mode:['mixed', 'args']\n```\n\nThis mode uses the function arguments to determine wether it needs\nto be called synchronously or asynchronously. When the last \nargument is a function, MakeSync assume the last argument is the 'done' callback. \nThere may be some issues when using other function arguments. Please refer \nto the section below.\n\n\n#### fixed numbers of args /  function arguments\n\nThis only applies when using the mixed-args mode and calling the function synchronously.\n\nThere are 2 strategies to resolve the confusion between the 'done' callback and other\nfunction argument, when those are passed at the end of the argument list:\n\n* use undefined as the last argument \n* pass the number of arguments expected (excluding the callback) to MakeSync.\n\n```coffeescript\n{Sync, MakeSync} = require 'make-sync'\n\nf = (a,b, _g, done) ->\n  res = a + b + _g()\n  done null, res\n\ng = -> 10\n\n# synchronizing (not using a fixed number of arg)  \nf1 = MakeSync f, mode:['mixed', 'args']\n\nSync ->\n  try f1 1, 2, g catch error \n    console.log \"f1 throws\" # thinks that g is the callback\n\n  res = f1 1, 2, g, undefined # ok when passing undefined at the end \n  console.log \"f1 sync ->\", res \n\n# passing a fixed number of args \nf2 = MakeSync f, {mode:['mixed','args'], num_of_args: 3}\n\nSync ->\n  res = f2 1, 2, g # it works \n  console.log \"f2 sync ->\", res \n```\n\n\n### mixed-fibers\n\n```coffeescript\nf = MakeSync f, mode:['mixed','fibers']\n```\n\nWhen using this mode, MakeSync checks wether a fiber is currently available,\nusing 'Fiber.current', and uses the sync or async mode accordingly.\n\n## return and error handling in sync mode\n\nThis can be configured using the sync-return option. \n\n\n### argument matcher\n\nArgument matchers works like the coffeescript arguments with splats. MakeSync will match the arguments passed\nto the callback using this pattern. If err is defined it will throw it, otherwise res will be\nreturned. (When using splats on res, res becomes an array)\n\n```coffeescript\n{Sync, MakeSync} = require 'make-sync'\n\n# err + res \nf = (done) -> done null, 'A'\nsyncF = MakeSync f, 'sync-return': 'err,res'\nSync ->\n  console.log syncF()\n\n# single res \nf = (done) -> done 'B'\nsyncF = MakeSync f, 'sync-return': 'res'\nSync ->\n  console.log syncF()\n\n# return error + res array \nf = (done) -> done null, 'C1', 'C2' \nsyncF = MakeSync f, 'sync-return': 'err, res...'\nSync ->\n  console.log syncF()\n \n# res array \nf = (done) -> done 'D1', 'D2' \nsyncF = MakeSync f, 'sync-return': 'res...'\nSync ->\n  console.log syncF()\n\n# the second result only\nf = (done) -> done 'E1', 'E2' , 'E3'\nsyncF = MakeSync f, 'sync-return': 'ignoreFirst, res, ignoreLast...'\nSync ->\n  console.log syncF()\n```\n\n\n### function\n\nIf matchers are not sufficient, you may use a function instead. This function will receive the same arguments\nas the callback, and its return will be the final result returned.\n\n```coffeescript\n{Sync, MakeSync} = require 'make-sync'\n\nf = (done) -> done null, 10, 20\noptions = \n  'sync-return': (err,res1,res2) -> res1 + res2\nsyncF = MakeSync f, options \nSync ->\n  console.log syncF()\n```\n\n### default\n\nIf not specified, this options is defaulted to:\n\n```coffeescript\n{'sync-return': 'err,res'}\n```\n\nThis means that MakeSync expect the function to pass an error, and one result to the callback. \nIt will ignore everything else.\n\n\n## options when calling on objects\n\nWhen calling MakeSync on an object,  MakeSync is called on all its \nmethods. \n\nIt is possible to configure the following: \n\n* inclusion and exclusion lists (per method basis)\n* num_of_args (per method basis)\n* sync-return (per method basis)\n* MakeSync mode (globally)\n\n```coffeescript\n{Sync, MakeSync} = require 'make-sync'\n\ng = -> 10\n\n# all the function are included by default, \n# then some are specifically excluded.\n# sync return is set per-function\nobj = \n  f1: (done) -> done null, 1\n  f2: (done) -> done null, 2\n  _f: (done) -> done 3\n  f3: (_g, done) -> done null, 4 + _g()\n  f4: (_g, done) -> done 5 + _g()\n  f5: (done) -> done null, 2\n\noptions =\n  mode: ['mixed', 'args']\n  exclude: ['f1', /^_/]\n  num_of_args:\n    f4:1\n  'sync-return':\n    '*': 'err,res'\n    _f: 'res'\n    f4: 'res'\n    f5: (err,res) -> res + 1\n\nMakeSync obj, options\n\nSync ->\n  try obj.f1() catch error then console.log \"f1 throws\" # f1 was excluded  \n  console.log 'f2 returns', obj.f2() # OK, not in the exclude list\n  try obj._f() catch error then console.log \"_f throws\" # _f was excluded\n  try obj.f3 g catch error \n    console.log \"f3 throws\" # num_of_args not set \n  console.log 'f4 returns', obj.f4 g # OK, num_of_args was set\n  console.log 'f5 returns', obj.f5() # uses sync return function\n\n# all the function are excluded \n# then some are specifically included.\nobj = \n  f1: (done) -> done 1\n  f2: (done) -> done 2\n  _f: (done) -> done 3\n  f3: (_g, done) -> done 4 + _g()\n  f4: (_g, done) -> done 5 + _g()\n  f5: (done) -> done 2\n\noptions = \n  mode: 'sync'\n  exclude: '*'\n  include: ['f1', 'f3']\n  'sync-return': 'res' # err is never pass to the done callback\nMakeSync obj, options\n\nSync ->\n  console.log '\\nf1 returns', obj.f1() # OK, f1 was included\n\n  try obj.f2() catch error then console.log \"f2 throws\" # f2 was excluded\n\n  console.log 'f3 returns', obj.f3 g # OK, f3 was included\n\n# exclude can also accept a simple string or a regex\noptions1 = exclude: 'f1'\noptions2 = exclude: /^_/\n```\n","scripts":{"test":"cake test"},"_npmUser":{"name":"sebv","email":"seb.vincent@gmail.com"},"keywords":["fibers","sync","synchronous"],"repository":{"url":"git@github.com:sebv/node-make-sync.git","type":"git"},"_npmVersion":"1.2.2","description":"synchronize functions and objects using fibers","directories":{},"maintainers":[{"name":"sebv","email":"seb.vincent@gmail.com"}],"dependencies":{"fibers":"1.0.x","underscore":"1.4.x","coffee-script":"1.4.x"},"readmeFilename":"README.md","devDependencies":{"mocha":"latest","should":"latest","sv-cake-utils":"latest"},"_id":"make-sync@0.1.3","version":"0.1.3"}