But why, I always see these things for what they are. Some sneaky caffeinated programmer kids at work with the booking system integrations, you should always double-check after us! After what came next, I started suspecting there’s some particularly defective developer marketing himself as a “Chief Hotel Booking Management System (HBMS) Professional with 10+ years experience in the field”.

I booked the next hotel for the two nights, with a discount, and walked there. Guess what? The room I booked was occupied, but they had another one, but not for two night, just one. In the end it worked out all right because there was that woman using the responsive, fully interactive, enterprise-ready ERP system “sheet of paper and a pencil” that allows you to reschedule bookings at will, with no programmers involved.

The rest of my trip went well, probably because I had little interaction with software stuff. The pizza place charged me twice, because they thought the first payment didn’t pass, but they gave the money back. Human problem, wasn’t it? (Of course not completely, some usability failure out there, but let’s leave it for what it is, shall we?)

The Return

I was riding the train from the airport, almost eager to get back to work writing things that mostly function. I was a bit worried they didn’t give me a call — was I supposed to just come to the office and figure out what to do next? Anyways, I made some calls and found out that the information about me starting my work got lost somewhere along the course of a month it’s been running around the infrastructure.

This got me a little worried: I haven’t spent a week in Moscow without work in over three years, and, besides, I was running low on money. I wasn’t angry with anyone in particular: who should I blame for the state of the industry? I’m just as guilty as anyone for letting it fall that low. it turned out not to be taht bad after all: the weather was good, and I got a chance to walk the empty city — everyone here in Moscow is too busy working hard to be out of office in the middle of the day.

My accidental vacation started along the fanfare of Nikita Prokopov’s software disenchantment. It’s depressing but, and even more depressive for being true. Let me pick a quote for you:

We cover shit with blankets just not to deal with it.

I’ve been subscribed to this blog for several years, and never knew the man was Russian. I should have guessed — where else can a man that depressed and dissatisfied with the state-of-the-world come from? The part that caught my atteniton was the Russian apps on the screenshots. From there I got onto Nikita’s russian-language blog.

Why must it be like this?

It’s a good the blog is in Russian — serves well to save the good people of the world from moscow-grade sadness. Somewhere in the comments on the fourth page I found a neat explanation for why the things in software are the way they are. I can’t find the particular comment any more, but I remember the gist and even spent some time elaborating on it.

Once a problem is solved by software at a minimum viable level, you don’t need programmers (we are crazy expensive) to actually make it work. The solution gets canned and distributed in a bundle that usually works, as long as you’re not getting too tricky:

• Edit a table of numbers? Excel!
• Write a text? Word!
• Send some data to another person? E-mail!
• Make a website? Wordpress!
• Edit an image? Photoshop!

The programmers are there to stick them into the holes of the abstraction. If you’re generating excel tables programatically from a database, or want your website to synchronize with a price list from a Googledoc, you need some programmers to duct-tape the systems together in unexpected ways (I’m working hard to stay away from shit-based metaphors, but feel free to make one yourself). These systems have a long train of backwards compatibility, they are a massive overkill for the job, but hey, they work just well enough.

I’m enraged by the lack of attention to static website generators. The idea is beautiful: pipe some markdowns through a template, get a set of static HTMLs and resources that can be host anywhere for, like, free! Why do people make their websites in Wordpress — have a MySQL database at work pushing the limits of storing static data, and PHP, rendering the pages at every request. Oh dear, the system was supposed to write blogs — how did they ever manage to bend it into e-commerce, landing pages and ERP front-ends?

No, I do know the answer to that — just hit a freelance farm to find a bunch of schoolchildren who can make you something that looks like a website in a week, for $50. I wouldn’t consider disrupting a business with that low profit margin — and who would?

And also

On Thursday I was watching my TV when the electricity died. It spent the evening randomly switching it on and off, then got stuck loading forever. The philips tech support was very sympathetic. “There’s some very high tech in there — a whole embedded system! How in the world did you expect it to survive the electricity shutdown?” they said. And yeah, sure, what did I expect from a system that had a piece of software in it?

Really, I should assume I write code at least marginally better-than-average and get into programming education. There’s a horrible shortage of material on learning actual programming (not “How to Use Technology X to Solve Problem Y”-style things) out there. I must to fight as well as I possibly can. You must, too (yes, you, the guy who actually read this all).

You’ve just seen a weekly snapshot of my thoughts pile. While taking another look at this website’s design to see if the the navigation is obscure enough to prevent the users from noticing the other posts (it probably is; I don’t think i’m changing it just yet) I noticed something horrible.

The blog’s address has thoughts pile in it. How is that name appropriate for the smart, boring and technical stuff I’ve come to post? I need to give the place some wildness it deserves. Klyukovka, ay, igray Balalaechka! Writing messy speculative posts is far more entertaining!

Let TS do its type inference

Here’s a sample typescript fragment from one of my projects:

1
2
3
4
5
6
7
8
9

function maxNumber(arr: number[]): number {
  let max: number = -Infinity;
  arr.forEach((x: number) => {
    if (x > max) {
      max = x;
    }
  });
  return max;
}

But TS compiler is really good at deducing types, so you don’t to be that explicit! TS deduces types from:

• initial values: const x = 10 is enough, no need for const x: number = 10;. This also works on default values, as in (x = false) => !x;
• array method types (any generic specifications, really): if arr is number[], than x in arr.forEach(x => ...) is obviously a number;
• return values: in our example, TS knows pretty well that max is a number, so the function returns a number.

So, our examle only needs one type annotation:

1
2
3
4
5
6
7
8
9

function maxNumber(arr: number[]) {
  let max = -Infinity;
  arr.forEach((x) => {
    if (x > max) {
      max = x;
    }
  });
  return max;
}

As a bonus, once we the annotations do not duplicate, we can easily change types without having to fix half a file. In our example, we changing arr to string[] immediately shows that we must also change the initial value of max to a string, ''.

As a rule of thumb, we only need explicit type annotations for:

• Function parameters: (x: number, y: number) => x + y;. As we’ve seen, default values will also do: (x = 0, y = 0) => x + y;.
• Empty containers: private users: IUser[] = [];. TS does not see an item, and can’t know its type.
• Values coming from outside the codebase. This one’s trickier, but think af an API call: get<IUser[]>('/users').
• (Yes, there are other cases, you’ll know it when you see one, don’t get mad at me).

Generally, annotate as few types as you can, then check the IDE hints to see if TS got it right. If not, help him.

Sometimes, just let types go

I’m absolutely guilty of this one: I’ve spent a day once typing a tricky low-level canvas util. Always remember that TS is supposed to help you, not stand in your way.

If you find yourself describing an especialy tricky type — a generic generic, or a polymorphic variadic function — stop and think if you really need it. Maybe the logic is just too obscure, and the fancy typings are just a symptom. Maybe you only use that function in one place, and it already works, so what’s the use?

With TS, you always have an easy way out — there’s no shame in dropping an any if it saves you a day! An explicit any is better than implicit beacuse if you’re feeling static on a Friday afternoon, you can grep your codebase for /: any/ and see if you can fix a couple.

Prevent compilation error buildup with global overrides

Accidentally you slip and ignore a TS error. The code still compiles, no harm done! But once your compilation log is several 10+ of bloody redness, it’s lost as a source of information about global project correctness. The generic advice is “look if it’s a real error, then either fix or re-type it”, but yes, I do have something specific in mind. Global type overrides are your friends!

Sure your browser targets support <Array>.find, or have a polyfill ready? Override the global Array type (courtesy of user75525 at SO)!

1
2
3

interface Array<T> {
  find(predicate: (search: T) => boolean): T;
}

Working on a legacy project with lodash loaded globally via a CDN? Throw it in:

1
2
3
4

import * as lodash from 'lodash';
declare global {
  const _: typeof lodash;
}

Using an obscure jQuery plugin? Global type overrides got you covered:

1
2
3

export interface JQuery {
  webuiPopover: (o: any) => JQuery;
}

Love the types you’re with

Hope this tips will help you be less depressed and more productive when working with TypeScript.

Oh AngularJS, what a reputation you’ve earned yourself

The context — where am I? (Help)

Some context first. I spent two years developing React front-ends. When offered a job on an AngularJS app, I was scared at first — we’ve all spent years making fun of it. The team lead was shaking a full Vue rewrite around not to scare the candidates off. The idea of playing around with Vue felt good (I’m a playful coder, don’t judge me), but Joel Spolsky’s spooky story of Netscape’s full rewrite had been growing on me for years. And well, there were features to be made, no time for the geek fun.

Now I’m gone from the project (no relation to the tech stack whatsoever), and the app is still moslty AngularJS. It’s in a good shape, and has all the modern things: webpack, babel, a sprinkle of React here and there. I feel I’ve made a good job by focusing on the business stuff.

The Problem — what’s wrong?

So, what was it I was gonna tell you kids about? We have a service that holds the list of users. Here it is, with all the ES6 exquisiteness:

1
2
3
4
5

class UserService {
  load() {
    return get('/users');
  }
}

Now, the component. All basic, too, just shows a list of users:

1
2
3
4
5
6
7
8
9
10
11
12
13

class UserListController {
  constructor(userService) {
    this.userService = userService;
    this.userService.load().then(users => {
      this.users = users;
    });
  }
}

angular.component('userList', {
  template: `<user-card ng-repeat="user in $ctrl.users" user="user"></user-card>`,
  controller: UserListController
});

But we can also add a user. Once the thing is done, we should update the list — it’s surely changed. But — oh no! — we have no way of doing it, because the data is stuck in UserListController.

1
2
3
4
5
6
7
8
9

class UserService {
  load() {
    return get('/users');
  }

  addUser(user) {
    return post('./users', user).then(/* oops */);
  }
}

The classic solution

The classic, ES3-level solution put forward by Justin Obney is to make users the property of UserService and never reassign it, only mutate (mute? mutilate?). The controller references the service property, and the angular view watch works, since users are shared by reference. Here’s the code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

class UserService {
  constructor() {
    this.users = [];
  }

  load() {
    return get('/users').then(users => {
      angular.copy(users, this.users);
    });
  }

  addUser(user) {
    return post('./users', user).then(() => this.load());
  }
}

class UserListController {
  constructor(userService) {
    this.userService = userService;
    this.users = this.userService.users;
    userService.load();
  }
}

There are three problems with this solution:

1. It’s fragile: if we accidentally reassign users either in the controller or the service, the whole scheme breaks down.
2. Instead of using normal javascript, you dance around the reference. The result of a well-behaved library function that does not mutate the data must be merged back into the original object.
3. The suggested way of caring for the reference, angular.copy, is angular-specific and makes a deep copy.

We can work around the first issue using TypeScript’s readonly properties, but the reference dance persists. Using TS2+ over AngularJS is a bit bipolar, too (exacly what I used on the project, but that’s beside the point).

Luckily, we can do much better — let me show you how.

The get / set solution

My solution relies on ES5 getters. Compatibility analysis, if I please? ES5 is nothing hot, it’s been around long enough to be considered the web standard. People who use IE9 are probably used to the web looking and working strange. Considering a modern framework — Vue or React? They require IE9+ anyways. So yes, we can use ES5 safely.

We do whatever we want to the service property, and declare a getter for it on the controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

class UserService {
  constructor() {
    this.users = [];
  }

  load() {
    return get('/users').then(users => {
      this.users = users;
    });
  }

  addUser(user) {
    return post('./users', user).then(() => this.load());
  }
}

class UserListController {
  constructor(userService) {
    this.userService = userService;
    userService.load();
  }

  get users() {
    return this.userService.users;
  }
}

Digest works normally. Mutate the users array in the service and the views update. Reassign in the service — the views still update. Mutate the array in a controller — the views update (a bug, not a feature? Maybe, but that’s how it goes). We can’t accidentally reassign the controller property because it only has a getter. And we have zero angular-specific code. The trick is backwards-compatible with the old one, so we needn’t rewrite the service all at once. Nice!

What good have we done?

Is this the holy grail? Certainly not. It requires some boilerplate, a 4-line getter per controller. We’re still stuck with the shaky shared ownersip: every controller can change the object. But this is an improvement over the old way.

For completeness, here are three other solutions off the top of my head:

1. Bind to service from the template: <user-card ng-repeat="user in $ctrl.userService.users"></user-card>. Bad, because it breaks abstraction layering — the view should not touch the service.
2. Make the service an event bus, do this.trigger('users.update', users); on every users change. Vanilla implementation is fragile (never forget to call trigger on update), but this might work with some structure around (though at this point we might as well stick mobx into the service).

3. $scope.$watch(() => this.userService.users, users => this.users = users). The effect is the same as in my solution, but at the cost of an extra digest iteration. Fall back to this one for ES3 complicance.

   Never say never to AngularJS — who knows how it’s gonna turn out. Drop a comment if the topic interests you! I still have a couple of AngularJS tricks down my sleeve to keep you safe. ES6 modules? String templates? CSS modules? Yes you can.

After some online research this analogy does not seem as fresh. Jeff Atwood in Coding: It’s Just Writing notes the similarities between William Strunk’s tips on writing and programming best practices, and then there’s Bert Wagner talking about the psychological similarities between coding and writing. On the other hand, the topic does not seem completely dead either, so watch me take another stab on it!

You produce text (not really)

On the surface, the end result of both writing and coding is text (as in “a sequence of words with some meaning”). However, this view breaks down once you think about it.

People in the software industry know that the value they provide is in solving business problems through code, not in writing code per se. Yet I don’t feel “shoving shitcode on top of shitcode to make things work” is the way to go. Let’s ban the whole business / technical argument for a minute.

This is not why people like open source

The users do not care for the code — they only see the GUI (or an API). What code you wrote in there is irreleveant as long as it works. When your users start caring about the code, it’s either because they want to learn from it, or because you screwed up and they have to dive in and debug. Not the primary use cases, huh?

But writers do indeed write texts. Or do they? A piece of writing is only valuable once you put it into your head and think about it. Very much like running a program, isn’t it? A good book is good because of the feelings and ideas it gives you, not because of the arrangement of words. Still not convinced? Think about play- and screenwriting: there is no text in a movie, yet the writing itself sure as hell is there.

Now, who carese about the word arrangements? Literature students do: they learn the ways to use words for the desired effect. When the text is so bad you can’t make sense of it (some lawyer mumbo-jumbo), you read it over and over again — isn’t it “text debugging”? Bingo on both!

You’re transmitting intention through text

And text is not even the best medium for what we the writers (see what I did there?) are trying to acheive. But we don’t know any better, so we settled on it somehow. We just want to communicate the ideas in our heads: algorithms, storylines, all is one.

The attempts to run away from the text? Check! Visual programming and comic books, respectively. However, people do not take these too seriously. Don’t grumble, give these some time and they will outshine the poor old text.

People think complex and long is cool (it is not)

What makes a writer good? It must be all those fancy baroque wordings! I heard James Joyce was good, and you can barely make sense of his books. The more grotesque plot twists, the merrier. But didn’t the greatest writers always talk about working hard to keep their works simple?

Now, what makes a programmer good? It must be all the fancy optimization hacks! How cool, this dude uses Singletons, Message Queues and Service Workers! No one can understand this code — what a work of genius! Sounds familiar? If you program, you know it’s bullshit. The best code for the job is the simplest code for the job — it’s easy to follow and does not strangle the performance with all the unnecessary layers of abstraction.

Teamwork is limited (it is still there)

Ten writers working on a book won’t write it ten times better or faster than one. Similarly, if you give one task to ten programmers with no management, they would drown in merge conflicts before delivering.

However, teamwork does exist in both industries, and is strikingly similar. Our code reviews = writers’ proofreading and editing. I remember Hemmingway’s quote about how cool his editor was, but I can’t seem to find that one now that there’s some proofreading software called Hemmingway — hope it edits sober. And you know how the code collapses into anarchy once there’s no one to stop you and watch with a clear eye.

The conclusion (I am so serious)

And I feel that as exploring other areas — art, cooking, construction, retail, what not — I will find even more structure to all of these. So make sure to come by when I publish more posts on “Programming is like Making Pasta”, “Hackathons are Like Doodling” and “Working in Outsource is Like Being an Illegal Plumber”.

When I tell my colleagues, friends, or students about it, they don’t take me seriously the first time. So, here we go again. If you have a docx (or xlsx, or pptx) file, you can unzip it with unzip proj.docx -d proj or any other unarchiver and get a folder with all the stuff that makes up the document:

From here, you can:

• quickly grab all the media from word/media
• work with the document (word/document) via an XML parser (or grep / sed, but it’s a secret)

And do all the other marvellous stuff — no Office or even GUI needed. Now go and spread the light of this newfound knowledge and never complain about docx again!

What Exactly to Rate Limit

Let’s get terminological matters out of the way first. Promises represent operations
that last a certain amount of time, while rate limiting is applied to discrete events.
Over its life, a promise starts and terminates (with a success or a failure, not
important now). It makes most sense to rate limit promise creations (starts).
Rate limiting promise resolutions can be done by appending a start-rate-limited
promise onto the end of the running promise. We could also limit the gap
between operations, but I have no idea how that would be useful.

Rate vs concurrency limiting

While both rate and concurrency limits are trying to prevent a client from
overloading the server by making too many calls too fast, they do not replace
one another, and are implemented differently.

Suppose an API is rate-limited to 1 request per second. Even 1-concurrent requests
break the rate limit if they complete in under 1s. On the other hand, if the
requests take 3 seconds to complete, we can only have 3 of them running at the same time:

1
2
3

...
 ...
  ...

We could derive a bunch of formulae to connect the concurrency, rate and
running time of operations, but that’s completely beside the point. The thing to
remember here is that without strict guarantees on operation duration you can
not replace concurrency limit with rate limit or vice versa.

Rate limiting individual operations

The simplest form of rate limiting is “1 operation per N seconds”. This one is
straightforward, but first we need a building block — the promise counterpart
of setTimeout:

1

const resolveAfter = ms => new Promise(ok => setTimeout(ok, ms));

resolveAfter is self-explanatory: it returns a promise that resolves after
the specified time has elapsed. Now, for the actual rate limiter:

1
2
3
4
5
6
7
8
9
10

function rateLimit1(fn, msPerOp) {
  let wait = Promise.resolve();
  return (...a) => {
    // We use the queue tail in wait to start both the
    // next operation and the next delay
    const res = wait.then(() => fn(...a));
    wait = wait.then(() => resolveAfter(msPerOp));
    return res;
  };
}

Now we can, as usual, wrap the promise and call with no worries, the operations
are magically delayed:

1
2
3
4

const slowFetch = rateLimit1(fetch, 1000);
Promise.all(urls.map(u => slowFetch(u)))
  .then(raw => Promise.all(raw.map(p => p.json())))
  .then(pages => console.log(pages));

The 1-rate-limiter can also be elegantly implemented on top of serializer
with the pitfall of unnecessarily delaying the first operation:

1
2
3
4

function rateLimit1(fn, msPerOp) {
  const wait = serializePromises(() => resolveAfter(msPerOp));
  return (...a) => wait().then(() => fn(...a));
}

Rate limiting multiple operations

Many APIs feature soft rate limits instead: they allow M request per N seconds.
That is not equivalent to 1 request per N/M seconds! Converting the multiple
rate limit into individual one does fulfil the rate limit, but is overly harsh
and non-optimal. Let’s see this through examples.

Difference from individual rate limit, by example

Suppose you’re flying a plane, and the airline allows 10 kg of luggage per
passenger. If you’re travelling with a girl, and have one 16-kg bag with both
your things. At the check-in desk you’re asked to take out half the stuff in
your bag to make two 8-kg items. While formally correct, it feels idiotic —
you still add the exact same weight to the plane! But now, why would you enforce
such a stupid restriction on your own operations if you can do better?

Closer to the topic, let’s try 2-req-per-2-sec rate limit for operations
lasting 2 seconds. If you immediately fire 2 requests, you’re done in 2 seconds:

1
2

----| 2 seconds, all done!
----|

Converting this into 1-req-per-1-sec delays the second request by 1s, and
now the same 2 requests take 3 seconds! You just lost a second for no reason.

1
2

----  | 3 seconds
  ----|

Understanding

To understand what we should do, let’s have a closer look at the 1-rate-limit.
We essentially make a queue of promises that never resolve closer than delay
apart. We use the resolutions to start the next operations, and don’t care
about its termination at all:

1

*--*--     *--*--

This view extends to N-rate-limit: create N independent queues and put these
into a circular queue (yes, a queue of queues makes a good in Soviet Russia
joke):

1
2
3

*--*-- *--*--
 *-- *--*--  *--
 *--  *-- *--    *--

The individual queues are unchanged, and never fire more than 1 operation per N
seconds. Thus, M queues can fire at most M operations during the window.

Implementing

With this plan in mind, we can generalize the implementation:

1
2
3
4
5
6
7
8
9
10
11
12

function rateLimit(fn, windowMs, reqInWindow = 1) {
  // A battery of 1-rate-limiters
  const queue = _.range(reqInWindow).map(() => rateLimit1(fn, windowMs));
  // Circular queue cursor
  let i = 0;
  return (...a) => {
    // to enqueue, we move the cursor...
    i = (i + 1) % reqInWindow;
    // and return the rate-limited operation.
    return queue[i](...a);
  };
}

Preventing queue overflow

Just as before, we run into problems if the operations are consistently inserted
into the queue faster than the rate limit. The solution is the same: once the
queue exceeds the specified number of items, we immediately reject the incoming
operations.

Combining with concurrency limiting

Now that we know how to limit both the rate and the number of simultaneously
running operations, and since neither is a substitute for another, we want a
way to combine the two limits. But can we build the joint rate/concurrency
limiter by composing the primitive limiters? Turns out we can, but should carefully
choose the order.

rateLimit(concurrencyLimit(fetch, N), ms), limits the rate at which the
operations enter the concurrency-limit queue. Serialized (1-concurrent) promises
rate-limited to 1 second break this combination. Suppose the first operation runs for
2 seconds, and during that time we throw 2 fast operations, O_2 and O_3 (say,
10 ms each) into the serializer. Instead of waiting for 1 second, the O_3 starts
right after O_2 completes, or 10ms after it starts, breaking the rate limit.

concurrencyLimit(rateLimit(fetch, ms), N) limits the number of operations in
the rate-limit queue. Since the rate limiter only sees N operations at a time,
it has no chance to fire more than N, which is exactly what we want.
Hence, Chaining Rule 1: limit concurrency before rate.

Use cases

The classic and most appropriate rate-limiting use case is for API requests.
But now that you know the pattern, you will see it in your own tasks and,
hopefully, use it ;-)

Promise-based rate limiting is a great way to quickly hack together a safe API
wrapper without depending on the underlying HTTP / TCP / WebSocket client.

Frankly, other use cases I can come up with off the top of my head (render
throttling and preventing too many e-mail notifications) are better served by
batching. Maybe, you’ll have better luck.

Summary

We’ve learnt to rate-limit promise-based APIs, both for the simple
“1-action-per-N-seconds” and the more general M-actions case. Together with the
previously discussed concurrency limiter, these patterns allow us to build robust
service gateways with node.js, safely call external APIs and do all the other
things you come up with.

Planning note: I’ve decided to throw away the excessively tricky part on load
balancing and go with super fun and useful posts on batching and handling failure.
I have RSS now, so be sure to stay tuned!

Advanced Promise Coordination Series

• Serialization and Concurrency Limiting
• Rate Limiting

Suppose we want a list of all the cafes in a mid-sized european country.However,
the API only lets you query the cafes by city. No problem — we have a list of
all the cities, and will send a request for each one, then assemble the results.

1
2
3
4
5
6
7
8
9
10
11
12
13

const cities = [
  "Abertamy",
  "Adamov (Blansko District)",
  "Aš",
  "Bakov nad Jizerou",
  "Bavorov",
  "Bechyně",
  "Bečov nad Teplou",
  "Bělá nad Radbuzou",
  "Bělá pod Bezdězem",
  // ... and 200 more
];
const loadCafes = city => fetch(`api.fivecircle.com/city/${city}`);

How Not to Chain Promises

The first naive attempts are no good:

1
2
3
4
5
6
7
8
9
10

// All gone in a glimpse of eye:
Promise.all(areas.map(loadCafes)).then(cafes => db.save(_.flatten(cafes)));
// Still not good
areas.forEach(area => {
  loadCafes(area).then(storeData);
});
// More of the same
for (let area in areas) {
  loadCafes(area).then(storeData);
}

Since promises start executing once created, each of these options fires all
the requests at once. With sane rate limiting restrictions, it will fail.
A less elaborate server could even crash.

We could, of course, use await:

1
2
3
4
5

let cafes = [];
for (let area of areas) {
  cafes = cafes.concat(await loadCafes(area));
}
storeData(cafes);

But I’m not a fan of this syntax — the code is now arguably C-like. I also
find error handling in promises cleaner. And now we have more preprocessing to do
for the code to work, which is nothing to be proud of. So let’s go on and write this
in pure promises instead.

Explicit Serialization

The best-known trick from this bunch is explicitly chaining an array of promises with
<Array>.reduce. It works best for fire-and-forget promises, like redux actions:

1
2
3

return actions.reduce(
  (pre, action) => before.then(() => action()),
  Promise.resolve());

However, assembling return values is a bit awkward:

1
2
3

areas.reduce((before, area) => {
  return before.then(acc => loadCafes(area).then(cafes => acc.concat(cafes)));
}, Promise.resolve([])).then(cafes => db.save(cafes));

Overall, this is good enough when you have an array of data you want to run the
actions on beforehand. But what if you don’t?

Implicit Serialization

We can actually write a wrapper for arbitrary promise-returning
functions that makes any call wait for the previous ones to finish. This wrapper
is completely transparent, leaving the function’s interface intact — good for
composability. Here it is:

1
2
3
4
5
6
7
8
9
10

function serializePromises(immediate) {
  // This works as our promise queue
  let last = Promise.resolve();
  return function (...a) {
    // Catch is necessary here — otherwise a rejection in a promise will
    // break the serializer forever
    last = last.catch(() => {}).then(() => immediate(...a));
    return last;
  }
}

Now we can just wrap our function and never have to worry about flooding the API again:

1
2

const loadCafesSafe = serializePromises(loadCafes);
Promise.all(areas.map(a => loadCafesSafe(a)));

It’s so easy it doesn’t warrant a library — just five lines of code. And we can
take this idea further with…

Concurrency Limiting

Serialization effectively forces our promises to run in one thread. To make them
go faster, we can generalize the serializer to allow not one, but at most N
promises to run simultaneously:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

function limitConcurrency(immediate, maxConcurrent) {
  // Each element holds its index, or a promise resolving with the index
  const workers = _.range(maxConcurrent);
  // Without this serialization, Promise.race would resolve with the same
  // worker whenever a concurrency-limited function was synchronously called
  // multiple times.
  const findWorker = serializePromises(() => Promise.race(workers));
  return function (...a) {
    // race resolves with the first free worker
    return findWorker().then(i => {
      // and here we start the action and update the worker correspondingly:
      const promise = immediate(...a);
      workers[i] = promise.then(() => i, () => i);
      return promise;
    });
  };
}

The idea is the same, but we replaced the single last promise with an array of
N workers and added some bookkeeping. This code packs promises into threads as
tightly as possible, with no idle time.

Also note that serializePromises is the same as a => limitConcurrency(a, 1).

If you want to impose joint limiting on several arbitrary functions, you can tweak the
code — I leave this to you as an exercise ;-)

Propagating Rate Errors

Now that our code manages a promise queue, we can see a potential problem in it.
The system can smooth activity spikes without propagating these upstream.
However, if the request rate is higher than what the upstream can handle for an
extended period of time, our queue can overfill and blow up the memory limit.

The problem still existed before we added the limiter, but would occurred
upstream instead. No wrapper can magically improve service throughput.

To handle these errors without crashing our process, we can put a hard limit on
queue size. Here’s how it can be done for the generic limitConcurrency:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

function limitConcurrency(immediate, maxConcurrent, maxQueue) {
  // this is our queue counter
  let queued = 0;
  const workers = _.range(maxConcurrent);
  const findWorker = serializePromises(() => Promise.race(workers));
  return function (...a) {
    if (queued >= maxQueue) {
      return Promise.reject(new Error('Max queue size reached'));
    }
    queued += 1;
    return findWorker().then(i => {
      queued -= 1;
      const promise = immediate(...a);
      workers[i] = promise.then(() => i, () => i));
      return promise;
    });
  };
}

Now, instead of uncontrollably enqueueing, the coordinator rejects when there’s
already too much work ahead. The consumers can handle these errors and retry later.

Use Cases

So far we’ve been discussing an example with API requests, and you might argue
that concurrency limiting functionality should be provided bt the HTTP client
library. That’s true, but the power of our promise-based strategy is its generality.
Here are some unorthodox use cases:

“Sloppy Transactions” with Serialization

Suppose an action involves reading an external data source, computing on the
response and issuing an update. If the source changes between the read and the
update, you’ve corrupted your data beyond repair. You can instead wrap the action
with our “promise serializer”. Of course, this assumes that the relevant data is only
accessed by your wrapper, and only by a single process. You can even build a
simple file-based database.

Prevent Notification Flood with Concurrency Limiting

A front-end idea. You probably have a notification area somewhere on
the screen. However, if a large batch of notifications just arrived, the users are
likely to miss some of those. But now you can treat the currently visible
notifications as the running threads and apply limitConcurrecny!

A similar use case for modal windows uses serialized promises — you can’t
show multiple modals at the same time, but now you can enqueue the next one
instead.

Web Worker Thread Pool

Finally, time for some cutting-edge tech. If your web app heavily uses web
workers for background processing, you can wrap web worker access with a
promise-based API, then use our wrapper to limit the number of simultaneously
active workers. With several kinds of specialized workers, you might choose to
use a multi-factory flavour of our limitConcurrecny instead. I’ll delve
deeper into this this case with an upcoming article on load balancing.

Summary

We’ve learnt how to force promises to run consecutively and even to limit the
number of pending promises to a specified number. This technique can be used
for safer back-end access, and its generality allows to use it for any
promise-based API.

I’m not too good at writing: the topics kept expanding in my head, and I have
had a hard time finishing this article. I have two other interesting
promise coordination patterns to handle in future articles of this series:

• Rate Limiting
• Load Balancing

Wish me luck writing these! If you have some tips or want to argue, drop me an
e-mail.

Advanced Promise Coordination Series

• Serialization and Concurrency Limiting
• Rate Limiting