npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

gensync

v1.0.0-beta.2

Published

Allows users to use generators in order to write common functions that can be both sync or async.

Downloads

141,113,639

Readme

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;
});

// Load and add the prefix synchronously:
const result = myOperation.sync("./some-file.js");

// Load and add the prefix asynchronously with promises:
myOperation.async("./some-file.js").then(result => {

});

// Load and add the prefix asynchronously with promises:
myOperation.errback("./some-file.js", (err, result) => {

});

This could even be exposed as your official API by doing

// Using the common 'Sync' suffix for sync functions, and 'Async' suffix for
// promise-returning versions.
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;
});

// In general cases
const code = readFileAndMore.sync("./file.js", "utf8");
readFileAndMore.async("./file.js", "utf8").then(code => {})
readFileAndMore.errback("./file.js", "utf8", (err, code) => {});

// In a generator being called indirectly with .sync/.async/.errback
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"),
  ]);
});