This post introduces the lightweight ($Q)orlate library.
A popular type of engagement that iVision is hired for is the architecture assessment. For assessment projects we analyze the existing system, weigh our own experience, industry standards and best practices against what we find, then provide feedback and a potential road map to iterate towards a desired solution. I’ve participated in everything from an over-arching analysis of the entire technology stack with associates from our data center, converged networking, and infrastructure practices to provide a business/IT roadmap for cloud readiness to a very targeted analysis of AngularJS implementations.
Recently I worked with a customer that built a very mature proof-of-concept using Angular in a system that had what I call “disconnected asynchronous processes.” These are processes that are truly “fire and sort of forget” because the message goes through message queues and workflows prior to a response being generated through a different channel. Although my first step is always to challenge this type of architecture (sometimes it’s implemented with the belief it is automatically faster or more scalable when there are other approaches that can achieve the same results with less complexity), in this case it truly seemed like the right architecture needed by that system.
I am constantly looking for opportunities to simplify and/or refactor code to reuse common components, algorithms, and strategies. This makes it easier to maintain and understand the code and provides developers with a toolbox to use so they can plug in the repeatable pattern and focus on what is unique about their part of the application. This led to me brainstorming what I’ve seen in these types of systems with Angular and I came up with three very distinct scenarios that I felt could be addressed with a lightweight Angular service.
1. Cached Requests
Angular has its own built-in mechanisms for controlling a cache. It is a common pattern for a service to asynchronously request information that is used by other components. Sometimes your app may get caught in a chicken-egg scenario when a component relies on a central service for information but must wait for that information to appear. For example, it may be necessary to retrieve security information from the server prior to building a menu or servicing requests.
There are a few ways to deal with this in Angular. One is to create the promise on the route, which will delay loading a view until the promise is satisfied. This isn’t an option if you aren’t using routes and sometimes your services may not be specific to a route. Another mechanism is simply to return a common promise. Multiple callbacks can be registered, so if the service keeps track of a single promise it can keep providing it, and even if it was resolved in the past the promise will be satisfied.
To see what I mean, take a look at this jsfiddle. Notice the second call happens long after the list was already populated, but the promise still fires and populates the second list (the list is populated after 1 second, and the second promise is requested after 2 seconds). The same promise is always returned.
The following figure shows this scenario (you can assume the server simply calls out to the database, the queue and handlers will make more sense for the other scenarios).
To enhance this scenario, ($Q)orlate provides an option to track multiple requests with timeouts. If timeout isn’t a concern or is handled locally, the straightforward use of $q will suffice. What ($Q)orlate does is provide a mechanism to automatically timeout and expire the request, so it keeps track of multiple requests even if you satisfy them with a single call.
The call to ($Q)orlate is passed an id that uniquely identifies the correlation (it will generate one for you if you do not pass one in). In this example a timeout is used to emulate the delayed response. Notice the resolution has an extra parameter for the correlation.
$timeout(function () {
_this.list = [1, 2, 3, 4, 5];
_this.qorlate.resolve(_this.id, _this.list);
}, qorlate.defaultTimeout + 100);
The service always returns a correlation. This is because qorlate will immediately return the last promise that was resolved or rejected, so any values (success or error) will be satisfied in the promise.
return this.qorlate({ id: this.id }).promise;
The consumers simply call the service with a standard promise, and it will either be satisfied once the data is loaded or rejected when it times out (in the example, the initial call times out but the subsequent call works because the data has been loaded). ($Q)orlate guarantees the promise, so even if a request is rejected from a timeout and the original call returns, later requests will be resolved immediately with the result.
Although this is one use case, ($Q)orlate is more suited to two other scenarios.
2. Discrete Disconnected Messages
I am purposefully using the label “disconnected” instead of “asynchronous” because a direct AJAX call can be asynchronous while it is still “connected” in the sense there is a clear path from the call to the resolution of the promise. What is less clear is when the message is sent to be processed, then returns through another channel such as a websocket. The top section of the following figure demonstrates this:
I call this a correlated event because even though the return event is surfaced independently of the request (i.e. via a Web Sockets connection), it is correlated to the initial request. For example, you might have a form that submits to a queuing system, is validated by a handler on the backend, then the response is routed back. In these cases, you still want to keep track of the message (i.e. if it times out it is probably good to inform the user) but the API might not be so clear. Consider something like this that you may be used to:
var id = 1;
function sendRequest() {
service.on('response', function (response) {
if (response.id === id) {
// do something
// and don't forget to unregister
}
}
service.send(id, request);
}
Basically you must keep track of your correlation and register to listen to all returned events, parse out the one you are interested in, then remember to unregister from the event (or just let it fire assuming the identifier won’t repeat), then finally fire off your message.
One of the nice things about the promise specification is that it helps make code cleaner and easier to read. What if you could do something like this instead:
service.request(id, request).
then(function success(response) {
// yes!
}, function error(err) {
// nope!
});
This is a straight promise. Is that possible, even when the mechanisms are disconnected? The answer is, “Yes.” The service simply needs to establish the promise with a correlation:
var correlation = this.qorlate();
return correlation.promise;
When the message comes in, the correlation is notified:
this.qorlate.resolve(correlation.id, response);
You can also reject the correlation, and the configurable timeout will also reject it automatically if the return message is not received within the timeout period. In the above example, the service generated the identifier. If you have GUIDs or other ways of matching messages, you can specify them when you generate the correlation and match it back. See a working example that demonstrates successful, failed, and timed out correlations here and view the source here.
If you look back at the second figure you’ll see there is another section near the bottom that indicates alerts raised by the server completely independent of the client. These are “broadcast” messages. You can certainly use mechanisms built into scope, but if you want a way that doesn’t rely on scope, still participates in digest loops (so no matter the mechanism for notification, you are always guaranteed to notify your subscribers in the context of a digest loop), and is testable, consider the next scenario.
3. Event Aggregator or Pub/Sub
The idea behind an event aggregator is straightforward. A central service “brokers” messages. You simply post your message to the service, any component interested subscribes, then the message is broadcast to the subscribers.
The subscription looks like this:
var cancel = q({subscribe:'addItem'}).always(function (item) {
rs.list.push(item);
});
In this case, the subscriber is responding any time the message is sent. An error/rejection method may also be added so if there is a problem with the transport it will notify subscribers. I do realize always is used in a different context relative to promises, but it made sense here because that’s what is happening – the message is always notifying the subscriber.
The call to ($Q)orlate will return a function to cancel the subscription – that’s as easy as calling cancel(); and you’re unsubscribed. The API to raise an event is no different:
q.resolve('addItem', (new Date()).getTime());
In fact, as you can see from the test specifications, you can overload the same identifier with promises and subscriptions. The module is fairly lightweight. It:
- Creates a promise when the function is called
- Sets a timer to reject the promise if the timeout is hit (this is configurable at the provider level and the individual call)
- Tracks the promises so when the correlation is resolved or rejected it can notify all consumers
- Generates a fresh set of promises for recurring subscriptions
Because it is all based on the underlying $q service, you do not have to worry about a return call being generated outside of a digest loop as $q is integrated with the root scope.
You can browse the source, offer feedback, generate pull requests, read the full documentation, run the tests and read the samples online at https://github.com/jeremylikness/qorlate. Enjoy!
