This module allows for developers to write common code that can share implementation details, hiding whether an underlying request happens synchronously or asynchronously. This is in contrast with many current Node APIs which explicitly implement the same API twice, once with calls to synchronous functions, and once with asynchronous functions.

Take for example {\ttfamily fs.\+read\+File} and {\ttfamily fs.\+read\+File\+Sync}, if you\textquotesingle{}re writing an API that loads a file and then performs a synchronous operation on the data, it can be frustrating to maintain two parallel functions.\hypertarget{md_sfcode_node_modules_gensync_README_autotoc_md11106}{}\doxysection{Example}\label{md_sfcode_node_modules_gensync_README_autotoc_md11106}

\begin{DoxyCode}{0}
\DoxyCodeLine{const fs = require("{}fs"{});}
\DoxyCodeLine{const gensync = require("{}gensync"{});}
\DoxyCodeLine{}
\DoxyCodeLine{const readFile = gensync(\{}
\DoxyCodeLine{  sync: fs.readFileSync,}
\DoxyCodeLine{  errback: fs.readFile,}
\DoxyCodeLine{\});}
\DoxyCodeLine{}
\DoxyCodeLine{const myOperation = gensync(function* (filename) \{}
\DoxyCodeLine{  const code = yield* readFile(filename, "{}utf8"{});}
\DoxyCodeLine{}
\DoxyCodeLine{  return "{}// some custom prefix\(\backslash\)n"{} + code;}
\DoxyCodeLine{\});}
\DoxyCodeLine{}
\DoxyCodeLine{// Load and add the prefix synchronously:}
\DoxyCodeLine{const result = myOperation.sync("{}./some-\/file.js"{});}
\DoxyCodeLine{}
\DoxyCodeLine{// Load and add the prefix asynchronously with promises:}
\DoxyCodeLine{myOperation.async("{}./some-\/file.js"{}).then(result => \{}
\DoxyCodeLine{}
\DoxyCodeLine{\});}
\DoxyCodeLine{}
\DoxyCodeLine{// Load and add the prefix asynchronously with promises:}
\DoxyCodeLine{myOperation.errback("{}./some-\/file.js"{}, (err, result) => \{}
\DoxyCodeLine{}
\DoxyCodeLine{\}); }

\end{DoxyCode}


This could even be exposed as your official API by doing 
\begin{DoxyCode}{0}
\DoxyCodeLine{// Using the common 'Sync' suffix for sync functions, and 'Async' suffix for}
\DoxyCodeLine{// promise-\/returning versions.}
\DoxyCodeLine{exports.myOperationSync = myOperation.sync;}
\DoxyCodeLine{exports.myOperationAsync = myOperation.async;}
\DoxyCodeLine{exports.myOperation = myOperation.errback; }

\end{DoxyCode}
 or potentially expose one of the async versions as the default, with a {\ttfamily .sync} property on the function to expose the synchronous version. 
\begin{DoxyCode}{0}
\DoxyCodeLine{module.exports = myOperation.errback;}
\DoxyCodeLine{module.exports.sync = myOperation.sync;}
\DoxyCodeLine{````}
\DoxyCodeLine{}
\DoxyCodeLine{}
\DoxyCodeLine{\#\# API}
\DoxyCodeLine{}
\DoxyCodeLine{\#\#\# gensync(generatorFnOrOptions)}
\DoxyCodeLine{}
\DoxyCodeLine{Returns a function that can be "{}await"{}-\/ed in another `gensync` generator}
\DoxyCodeLine{function, or executed via}
\DoxyCodeLine{}
\DoxyCodeLine{* `.sync(...args)` -\/ Returns the computed value, or throws.}
\DoxyCodeLine{* `.async(...args)` -\/ Returns a promise for the computed value.}
\DoxyCodeLine{* `.errback(...args, (err, result) => \{\})` -\/ Calls the callback with the computed value, or error.}
\DoxyCodeLine{}
\DoxyCodeLine{}
\DoxyCodeLine{\#\#\#\# Passed a generator}
\DoxyCodeLine{}
\DoxyCodeLine{Wraps the generator to populate the `.sync`/`.async`/`.errback` helpers above to}
\DoxyCodeLine{allow for evaluation of the generator for the final value.}
\DoxyCodeLine{}
\DoxyCodeLine{\#\#\#\#\# Example}
\DoxyCodeLine{}
\DoxyCodeLine{```js}
\DoxyCodeLine{const readFile = function* () \{}
\DoxyCodeLine{  return 42;}
\DoxyCodeLine{\};}
\DoxyCodeLine{}
\DoxyCodeLine{const readFileAndMore = gensync(function* ()\{}
\DoxyCodeLine{  const val = yield* readFile();}
\DoxyCodeLine{  return 42 + val;}
\DoxyCodeLine{\});}
\DoxyCodeLine{}
\DoxyCodeLine{// In general cases}
\DoxyCodeLine{const code = readFileAndMore.sync("{}./file.js"{}, "{}utf8"{});}
\DoxyCodeLine{readFileAndMore.async("{}./file.js"{}, "{}utf8"{}).then(code => \{\})}
\DoxyCodeLine{readFileAndMore.errback("{}./file.js"{}, "{}utf8"{}, (err, code) => \{\});}
\DoxyCodeLine{}
\DoxyCodeLine{// In a generator being called indirectly with .sync/.async/.errback}
\DoxyCodeLine{const code = yield* readFileAndMore("{}./file.js"{}, "{}utf8"{}); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gensync_README_autotoc_md11107}{}\doxysubsubsection{Passed an options object}\label{md_sfcode_node_modules_gensync_README_autotoc_md11107}

\begin{DoxyItemize}
\item {\ttfamily opts.\+sync}

Example\+: {\ttfamily (...args) =$>$ 4}

A function that will be called when {\ttfamily .sync()} is called on the {\ttfamily gensync()} result, or when the result is passed to {\ttfamily yield$\ast$} in another generator that is being run synchronously.

Also called for {\ttfamily .async()} calls if no async handlers are provided.
\item {\ttfamily opts.\+async}

Example\+: {\ttfamily async (...args) =$>$ 4}

A function that will be called when {\ttfamily .async()} or {\ttfamily .errback()} is called on the {\ttfamily gensync()} result, or when the result is passed to {\ttfamily yield$\ast$} in another generator that is being run asynchronously.
\item {\ttfamily opts.\+errback}

Example\+: {\ttfamily (...args, cb) =$>$ cb(null, 4)}

A function that will be called when {\ttfamily .async()} or {\ttfamily .errback()} is called on the {\ttfamily gensync()} result, or when the result is passed to {\ttfamily yield$\ast$} in another generator that is being run asynchronously.

This option allows for simpler compatibility with many existing Node APIs, and also avoids introducing the extra even loop turns that promises introduce to access the result value.
\item {\ttfamily opts.\+name}

Example\+: {\ttfamily \char`\"{}read\+File\char`\"{}}

A string name to apply to the returned function. If no value is provided, the name of {\ttfamily errback}/{\ttfamily async}/{\ttfamily sync} functions will be used, with any {\ttfamily Sync} or {\ttfamily Async} suffix stripped off. If the callback is simply named with ES6 inference (same name as the options property), the name is ignored.
\item {\ttfamily opts.\+arity}

Example\+: {\ttfamily 4}

A number for the length to set on the returned function. If no value is provided, the length will be carried over from the {\ttfamily sync} function\textquotesingle{}s {\ttfamily length} value.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_gensync_README_autotoc_md11108}{}\doxyparagraph{Example}\label{md_sfcode_node_modules_gensync_README_autotoc_md11108}

\begin{DoxyCode}{0}
\DoxyCodeLine{const readFile = gensync(\{}
\DoxyCodeLine{  sync: fs.readFileSync,}
\DoxyCodeLine{  errback: fs.readFile,}
\DoxyCodeLine{\});}
\DoxyCodeLine{}
\DoxyCodeLine{const code = readFile.sync("{}./file.js"{}, "{}utf8"{});}
\DoxyCodeLine{readFile.async("{}./file.js"{}, "{}utf8"{}).then(code => \{\})}
\DoxyCodeLine{readFile.errback("{}./file.js"{}, "{}utf8"{}, (err, code) => \{\}); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gensync_README_autotoc_md11109}{}\doxysubsection{gensync.\+all(iterable)}\label{md_sfcode_node_modules_gensync_README_autotoc_md11109}
{\ttfamily Promise.\+all}-\/like combinator that works with an iterable of generator objects that could be passed to {\ttfamily yield$\ast$} within a gensync generator.\hypertarget{md_sfcode_node_modules_gensync_README_autotoc_md11110}{}\doxysubsubsection{Example}\label{md_sfcode_node_modules_gensync_README_autotoc_md11110}

\begin{DoxyCode}{0}
\DoxyCodeLine{const loadFiles = gensync(function* () \{}
\DoxyCodeLine{  return yield* gensync.all([}
\DoxyCodeLine{    readFile("{}./one.js"{}),}
\DoxyCodeLine{    readFile("{}./two.js"{}),}
\DoxyCodeLine{    readFile("{}./three.js"{}),}
\DoxyCodeLine{  ]);}
\DoxyCodeLine{\}); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_gensync_README_autotoc_md11111}{}\doxysubsection{gensync.\+race(iterable)}\label{md_sfcode_node_modules_gensync_README_autotoc_md11111}
{\ttfamily Promise.\+race}-\/like combinator that works with an iterable of generator objects that could be passed to {\ttfamily yield$\ast$} within a gensync generator.\hypertarget{md_sfcode_node_modules_gensync_README_autotoc_md11112}{}\doxysubsubsection{Example}\label{md_sfcode_node_modules_gensync_README_autotoc_md11112}

\begin{DoxyCode}{0}
\DoxyCodeLine{const loadFiles = gensync(function* () \{}
\DoxyCodeLine{  return yield* gensync.race([}
\DoxyCodeLine{    readFile("{}./one.js"{}),}
\DoxyCodeLine{    readFile("{}./two.js"{}),}
\DoxyCodeLine{    readFile("{}./three.js"{}),}
\DoxyCodeLine{  ]);}
\DoxyCodeLine{\}); }

\end{DoxyCode}
 