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

q-connection

v0.6.1

Published

An inter-worker asynchronous promise communication system.

Downloads

12

Readme

Build Status

Asynchronous Remote Objects

This library makes it possible for objects to communicate asynchronously between memory-isolated JavaScript contexts, including pipelining interactions with results. Promises serve as proxies for remote objects.

Q-Connection works in Node and other CommonJS module loaders like Browserify, Mr, and Montage.

This is how it looks:

var Q = require("q");
var Connection = require("q-connection");
var remote = Connection(port, local);

The remote object is a promise for the local object on the other side of the connection. Likewise, the other side of the connection will get a promise for your local object. You are not obliged to provide a local object, depending on which end of the connection is providing a service.

If the remote or local object is not serializable, like functions or objects with methods, the other side will receive a promise but you will have to “send messages” to the promise instead of interacting directly with the remote object. When you invoke a method on a remote object, you get a promise for the result and you can immediately pipeline a method call on the result. This is the secret sauce.

The port is any W3C message port, web worker, or web socket. In the W3C’s infinite wisdom, these do not have a unified API, but Q-Connection will normalize them internally.

// To communicate with objects in a worker
var worker = new Worker("worker.js");
var child = Connection(worker, local);
// Inside a worker, to communicate with the parent
var parent = Connection(this);
// To communicate with a remote object on the other side of
// a web socket
var socket = new WebSocket("ws://example.com");
var remote = Connection(socket, local);
// To communicate with a single frame on the same origin
// (multiple frames will require some handshaking event sources)
var iframe = document.frames[0];
var child = Connection(iframe.contentWindow, local, {
    origin: window.location.origin
})
// To communicate with a parent frame on the same origin
var child = Connection(window, local, {
    origin: window.location.origin
})
// With a message port
var port = new MessagePort();
var near = Connection(port[0]);
var far = Connection(port[1]);

Your local value can be any JavaScript value, but it is most handy for it to be an object that supports an API and cannot be serialized with JSON.

var Q = require("q");
var counter = 0;
var local = {
    "next": function () {
        return counter++;
    }
};

In this case, the local object has a "next" function that returns incremental values. Since the function closes on local state (the counter), it can't be sent to another process.

On the other side of the connection, we can asynchronously call the remote method and receive a promise for the result.

remote.invoke("next")
.then(function (id) {
    console.log("counter at", i);
});

The connection is bi-directional. Although you do not need to provide and use both local and remote values on both sides of a connection, they are available.

You can asynchronously interact with any value using the Q API. This chart shows the analogous operations for interacting with objects synchronously and asynchronously.

synchronous                asynchronous
------------------         -------------------------------
value.foo                  promise.get("foo")
value.foo = value          promise.put("foo", value)
delete value.foo           promise.del("foo")
value.foo(...args)         promise.post("foo", [args])
value.foo(...args)         promise.invoke("foo", ...args)
value(...args)             promise.fapply([args])
value(...args)             promise.fcall(...args)

All of the asynchronous functions return promises for the eventual result. For the asynchronous functions, the value may be any value including local values, local promises, and remote promises.

The benefit to using the asynchronous API when interacting with remote objects is that you can send chains of messages to the promises that the connection makes. That is, you can call the method of a promise that has not yet been resolved, so that message can be immediately sent over the wire to the remote object. This reduces the latency of interaction with remote objects by removing network round-trips.

A chain of dependent operations can be contracted from:

<-client     server->
a..
   ''--..
         ''--..
               ''--..
             ..--''
       ..--''
 ..--''
b..
   ''--..
         ''--..
               ''--..
             ..--''
       ..--''
 ..--''
c..
   ''--..
         ''--..
               ''--..
             ..--''
       ..--''
 ..--''

Down to:

<-client     server->
a..
b..''--..
c..''--..''--..
   ''--..''--..''--..
         ''--..--''..
       ..--''..--''..
 ..--''..--''..--''
 ..--''..--''
 ..--''

Where the dotted lines represent messages traveling through the network horizontally, and through time vertically.

Ports

Q-Connection handles a variety of message ports or channel types. They are all internally converted into a Q Channel. If you are using a message channel that provides a different API than this or a WebWorker, WebSocket, or MessagePort, you can adapt it to any of these interfaces and Q-Connection will handle it.

This is probably the simplest way to create a channel duck-type, assuming that you’ve got a connection instance of the Node variety.

var port = {
    postMessage: function (message) {
        connection.send(message);
    },
    onmessage: null // gets filled in by Q-Connection
};
connection.on("message", function (data) {
    port.onmessage({data: ""})
});
var remote = Connection(port, local);

Here's an example showing adapting socket.io to the message port.

var port = {
  postMessage: function (message) {
    socket.emit("message", message);
  },
  onmessage: null // gets filled in by Q-Connection
};
socket.on("message", function(data) {
  port.onmessage({data: data});
});
var remote = Connection(port, local);

Q Channels

  • get() returns a promise for the next message from the other side of the connection. get may be called any number of times independent of when messages are actually received and each call will get a promise for the next message in sequence.
  • put(message) sends a message to the remote side of the connection.
  • close(reason_opt) indicates that no further messages will be sent.
  • closed a promise that is fulfilled with the reason for closing.

Q-Connection exports an indefinite Queue that supports this API which greatly simplifies the implementation of adapters.

  • get() returns a promise for the next value in order that is put on the queue. get may be called any number of times, regardless of whether the corresponding value is put on the queue before or after the get call.
  • put(value) puts a message on the queue. Any number of messages can be put on the queue, indepent of whether and when the corresponding get is called.
  • close(reason_opt) indicates that no further messages will be put on the queue and that any promises for such messages must be rejected with the given reason.
  • closed a promise that is fulfilled when and if the queue has been closed.

Web Workers and Message Ports

Q-Connection detects ports by their postMessage function.

  • postMessage(message)
  • onmessage(handler(message))

Web Sockets

Q-Connection detects Web Sockets by their send function. It takes the liberty to start the socket and listens for when it opens.

  • send(message)
  • addEventListener(event, handler(event))
  • start()
  • open event
  • close event

Memory

Q-Connection uses an LRU cache of specified size. The default size is infinite, which is horribly leaky. Promises between peers will stick around indefinitely. This can be trimmed to something reasonable with the max option.

var remote = Connection(port, local, {max: 1024});

The least frequently used promises will be collected. If the remote attempts to communicate with a collected promise, the request will be ignored. The minimum working set will vary depending on the load on your service.

To be notified when communication is attempted with a collected promise set the onmessagelost option.

var remote = Connection(port, local, {
    max: 1024,
    onmessagelost: function (message) {
        console.log("Message to unknown promise", message);
    }
});