What is gensync?
The gensync package allows for the creation and management of generator functions or functions that return promises, enabling them to be used in a synchronous-like manner without blocking the event loop. It provides a way to write asynchronous code that looks and behaves like synchronous code, making it easier to read and maintain. This can be particularly useful in scenarios where asynchronous operations need to be performed in a specific sequence or when dealing with complex control flow.
What are gensync's main functionalities?
Handling asynchronous operations synchronously
This feature allows for the execution of asynchronous operations in a way that resembles synchronous code execution. The code sample demonstrates how to define an asynchronous operation using gensync and execute it, handling the result with a promise.
const gensync = require('gensync');
const asyncOperation = gensync(function* () {
const result = yield Promise.resolve('Result of async operation');
return result;
});
asyncOperation().then(console.log); // Logs: 'Result of async operation'
Error handling in asynchronous operations
This feature demonstrates how gensync can be used to handle errors in asynchronous operations in a synchronous-like manner. The code sample shows how to catch and handle errors using try/catch blocks within a gensync function.
const gensync = require('gensync');
const asyncOperationWithError = gensync(function* () {
try {
const result = yield Promise.reject(new Error('Error occurred'));
return result;
} catch (error) {
return 'Error handled';
}
});
asyncOperationWithError().then(console.log); // Logs: 'Error handled'
Other packages similar to gensync
co
The 'co' package is similar to gensync in that it also allows for managing and handling asynchronous operations using generator functions. However, 'co' focuses more on leveraging generators to simplify asynchronous code, whereas gensync provides a broader set of utilities for working with both generator functions and functions returning promises.
bluebird
While 'bluebird' is primarily known as a promise library offering enhanced performance and additional features compared to native Promises, it also includes utilities for converting generator functions into functions that return promises, similar to what gensync offers. However, gensync is more focused on the seamless integration of synchronous and asynchronous code through generators and promises.
gensync
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 fs.readFile
and fs.readFileSync
, if you'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.
Example
const fs = require("fs");
const gensync = require("gensync");
const readFile = gensync({
sync: fs.readFileSync,
errback: fs.readFile,
});
const myOperation = gensync(function* (filename) {
const code = yield* readFile(filename, "utf8");
return "// some custom prefix\n" + code;
});
const result = myOperation.sync("./some-file.js");
myOperation.async("./some-file.js").then(result => {
});
myOperation.errback("./some-file.js", (err, result) => {
});
This could even be exposed as your official API by doing
exports.myOperationSync = myOperation.sync;
exports.myOperationAsync = myOperation.async;
exports.myOperation = myOperation.errback;
or potentially expose one of the async versions as the default, with a
.sync
property on the function to expose the synchronous version.
module.exports = myOperation.errback;
module.exports.sync = myOperation.sync;
API
gensync(generatorFnOrOptions)
Returns a function that can be "await"-ed in another gensync
generator
function, or executed via
.sync(...args)
- Returns the computed value, or throws.
.async(...args)
- Returns a promise for the computed value.
.errback(...args, (err, result) => {})
- Calls the callback with the computed value, or error.
Passed a generator
Wraps the generator to populate the .sync
/.async
/.errback
helpers above to
allow for evaluation of the generator for the final value.
Example
const readFile = function* () {
return 42;
};
const readFileAndMore = gensync(function* (){
const val = yield* readFile();
return 42 + val;
});
const code = readFileAndMore.sync("./file.js", "utf8");
readFileAndMore.async("./file.js", "utf8").then(code => {})
readFileAndMore.errback("./file.js", "utf8", (err, code) => {});
const code = yield* readFileAndMore("./file.js", "utf8");
Passed an options object
-
opts.sync
Example: (...args) => 4
A function that will be called when .sync()
is called on the gensync()
result, or when the result is passed to yield*
in another generator that
is being run synchronously.
Also called for .async()
calls if no async handlers are provided.
-
opts.async
Example: async (...args) => 4
A function that will be called when .async()
or .errback()
is called on
the gensync()
result, or when the result is passed to yield*
in another
generator that is being run asynchronously.
-
opts.errback
Example: (...args, cb) => cb(null, 4)
A function that will be called when .async()
or .errback()
is called on
the gensync()
result, or when the result is passed to yield*
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.
-
opts.name
Example: "readFile"
A string name to apply to the returned function. If no value is provided,
the name of errback
/async
/sync
functions will be used, with any
Sync
or Async
suffix stripped off. If the callback is simply named
with ES6 inference (same name as the options property), the name is ignored.
-
opts.arity
Example: 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 sync
function's
length
value.
Example
const readFile = gensync({
sync: fs.readFileSync,
errback: fs.readFile,
});
const code = readFile.sync("./file.js", "utf8");
readFile.async("./file.js", "utf8").then(code => {})
readFile.errback("./file.js", "utf8", (err, code) => {});
gensync.all(iterable)
Promise.all
-like combinator that works with an iterable of generator objects
that could be passed to yield*
within a gensync generator.
Example
const loadFiles = gensync(function* () {
return yield* gensync.all([
readFile("./one.js"),
readFile("./two.js"),
readFile("./three.js"),
]);
});
gensync.race(iterable)
Promise.race
-like combinator that works with an iterable of generator objects
that could be passed to yield*
within a gensync generator.
Example
const loadFiles = gensync(function* () {
return yield* gensync.race([
readFile("./one.js"),
readFile("./two.js"),
readFile("./three.js"),
]);
});