# Getting the integer part from a number in Javascript

Just a thing I learned today: using the bitwise not operator (~) on a number in Javascript ignores its fractional part (it converts it to integer first), therefore using it twice gives you the integer part of original number. Thanks to fetishlace for clarifications.

Notes:

• this is equivalent to (int)number in languages that support the int type
• this is equivalent to Math.trunc for numbers in the integer range
• this is equivalent to Math.floor only for positive numbers in the integer range

Examples:
`~~1.3 = 1`
`~~-6.5432 = -6`
`~~(2 ** 32 + 0.5) = 0`
`~~10000000000 = 1410065408`

P.S. If you don't know what ** is, it's called the Exponentiation operator and it came around in Javascript ES2016 (ES7) and it is the equivalent of Math.pow. `2 ** 3 = Math.pow(2,3) = 8`

# The Javascript sort is slow and stupid (or is it?)

I was looking into the concept of partial sorting, something that would help in a scenario where you want the k smaller or bigger items from an array of n items and k is significantly smaller than n. Since I am tinkering with LInQer, my implementation for LINQ methods in Javascript, I wanted to tackle the OrderBy(...).Take(k) situation. Anyway, doing that I found out some interesting things.

First, the default Javascript array .sort function has different implementations depending on browser and by that I mean different sort algorithms. Chrome uses insertion sort and Firefox uses merge sort. None of them is Quicksort, the one that would function best when the number of items is large, but that has worst case complexity O(n^2) when the array is already sorted (or filled with the same value).

I've implemented a custom function to do Quicksort and after about 30000 items it becomes faster than the default one.  For a million items the default sort was almost three times slower than the Quicksort implementation. To be fair, I only tested this on Chrome. I have suspicions that the merge sort implementation might be better.

I was reporting in a previous version of this post that QuickSort, implemented in Javascript, was faster than the default .sort function, but it seems this was only an artifact of the unit tests I was using. Afterwards, I've found an optimized version of quicksort and it performed three times faster on ten million integers. I therefore conclude that the default sort implementation leaves a lot to be desired.

Second, the .sort function is by default alphanumeric. Try it: [1,2,10].sort() will return [1,10,2]. In order to do it numerically you need to hack away at it with [1,2,10].sort((i1,i2)=>i1-i2). In order to sort the array based on the type of item, you need to do something like: [1,2,10].sort((i1,i2)=>i1>i2?1:(i1<i2?-1:0)).

Javascript has two useful functions defined on the prototype of Object: toString and valueOf. They can also be overwritten, resulting in interesting hacks. For some reason, the default .sort function is calling toString on the objects in the array before sorting and not valueOf. Using the custom comparers functions above we force using valueOf. I can't test this on primitive types though (number, string, boolean) because for them valueOf cannot be overridden.

And coming back to the partial sorting, you can't do that with the default implementation, but you can with Quicksort. Simply do not sort any partition that is above and below the indexes you need to get the items from. The increases in time are amazing!

There is a difference between the browser implemented sort algorithms and QuickSort: they are stable. QuickSort does not guarantee the order of items with equal sort keys. Here is an example: [1,3,2,4,5,0].sort(i=>i%2) results in [2,4,0,1,3,5] (first even numbers, then odd, but in the same order as the original array). The QuickSort order depends on the choice of the pivot in the partition function, but assuming a clean down the middle index, the result is [4,2,0,5,1,3]. Note that in both cases the requirement has been met and the even numbers come first.

# LInQ in Javascript: LInQer!

## Major Update

I've rewritten the entire thing into a Typescript library. I've abandoned the separation into three different Javascript files. Now it is only one having everything you need.

I haven't tested it in the wild, but you can get the new version here:

Documentation online: https://siderite.github.io/LInQer-ts

Using the library in the browser directly: https://siderite.github.io/LInQer-ts/lib/LInQer.js and https://siderite.github.io/LInQer-ts/lib/LInQer.min.js

Please give me all the feedback you can! I would really love to hear from people who use this in:

• Typescript
• Node.js
• browser web sites

## And now for the old post

Update: The npm package can now be used in Node.js and Typescript (with Intellisense). Huge optimizations on the sorting and new extra functions published.

Update: Due to popular demand, I've published the package on npm at https://www.npmjs.com/package/@siderite/linqer. Also, while at it, I've moved the entire code to Typescript, fixed a few issues and also create the Linqer.Slim.js file, that only holds the most common methods. The minimized version can be found at https://siderite.github.io/LInQer/LInQer.slim.min.js and again you can use it freely on your websites. Now, I hope you can use it in Node JS as well, I have no idea how to test it and frankly I don't want to. I've also added a tests.slim.html that only tests the slim version of Linqer. This version is now official and I will try to limit any breaking changes from now on. WARNING: Now the type is Linqer.Enumerable, not just Enumerable as before. If you are already using it in code, just do `const Enumerable = Linqer.Enumerable;` and you are set to go.

Update: LInQer can now be found published at https://siderite.github.io/LInQer/LInQer.min.js and https://siderite.github.io/LInQer/LInQer.extra.min.js and you can freely use it in your web sites. Source code on GitHub.

Update: All the methods in Enumerable are now implemented, and some extra ones as well. Optimizations have been developed for operations like orderBy().take() and .count().

This entire thing started from a blog post that explained something that seems obvious in retrospect, but you have to actually think about it to realise it: Array functions in Javascript may seem similar to LInQ methods in C#, but they work with arrays! Every time you filter or you map something you create a new array! The post suggested creating functions that would use the modern Javascript features of iterators and generator functions and supplant the standard Array functions. It was brilliant!

And then the post abruptly veered and swerved into a tree. The author suggested we add the pipe operator to Javascript, just like they have in functional programming languages, so that we can use those static functions with hash characters as placeholders and... ugh! It was horrid! So I decided to solve the problem in a way that was more compatible with my own sensibilities: make it work just like LInQ (or at least like the Java streams).

This is how LInQer was born. You can find the sources on GitHub at /Siderite/LInQer. The library introduces a class called Enumerable, which can wrap any iterable (meaning arrays, but also generator functions or anything that supports for...of), then expose the methods that the Enumerable class in .NET exposes. There is even a unit test file called tests.html. Open it in the browser and see the supported methods. As you can see in the image of the blog post, the same logic (filtering, mapping and slicing a 10 million item array) took 2000ms using standard Array functions and 150ms using the Enumerable class.

"But wait! It says there that Enumerable exposes static methods! What exactly did you improve?", you will ask. In .NET we have something called "extension methods", which are indeed static methods that the language understands apply to specific classes or interfaces and allows you to call them like you would instance methods. So a method that looks like `public static int Sum(this IEnumerable<int> enumerable)` can be used statically `Enumerable.Sum(arr)` or like an instance method `arr.Sum()`. It's syntactic sugar. But enough about C#, in Javascript I've implemented Enumerable as a wrapper, as Javascript doesn't know about interfaces or static extension methods. This class then exposes prototype functions that work the same way as in LInQ.

Here is where the magic happens:

``````Enumerable.prototype = {
[Symbol.iterator]() {
const iterator = this._src[Symbol.iterator].bind(this._src);
return iterator();
},
``````

In other words I wrap _src (the original iterable object) in my Enumerable by exposing the same iterator for both! Now both initial object and its wrapper can be used in for...of loops. The difference is that the wrapper now exposes all that juicy functionality. Let's see a simple example: select (which is the logical equivalent of Array.map):

``````select(op) {
_ensureFunction(op);
const gen = function* () {
for (const item of this) {
yield op(item);
}
}.bind(this);
return new Enumerable(gen());
},
``````

Here I am constructing a generator function which I bind to the Enumerable instance so that inside it 'this' is always that instance. Then I am returning the wrapper over the generator. In the function I am yielding the result of the op function on each item. Because of how generator functions work, only while iterating will it need to do its work, meaning that if I use the Enumerable into a for...of loop and breaking after three items, the op function will only be applied on those items, not on all of them. In order to use the Enumerable object in regular code, that works with arrays, you just use `.toArray` and you are done!

Let's see the code in the tests used to compare the standard Array function use with Enumerable:

``````// this is the large array we are using in both code blocks:
const largeArray = Array(10000000).fill(10);

// Standard Array functions
const someCalculation = largeArray
.filter(x=>x===10)
.map(x=>'v'+x)
.slice(100,110);
// Enumerable
const someCalculation = Linqer.Enumerable.from(largeArray)
.where(x=>x===10)
.select(x=>'v'+x)
.skip(100)
.take(10)
.toArray();
``````

There are differences from the C# Enumerable, of course. Some things don't make sense, like `thenBy` after `orderBy`. It can be done, but it's complicated and in my career I've only used thenBy twice! `toDictionary`, `toHashSet`, `toLookup`, `toList` have no meaning in Javascript. Use instead `toMap`, `toSet`, `toObject`, `toArray`. Last, but not least... `join`. Join is so complicated to use in LInQ that I almost never used it. Also, joining is usually done in the database, so I rarely needed it. I didn't see a point in implementing it. Cast and AsEnumerable also didn't make sense. But I implemented them anyway! :) Cast and OfType are using either a class or a string to determine if an item is "of type" and join works just like in C#.

But don't fret. Any function that you want to add to this can simply be added by your own code into `Enumerable.prototype`! So if you really need something custom, it's easy to add without modifying the original library.

There is one disadvantage for the prototype approach and the reason why the initial article suggested to use standalone functions: tree-shaking, the fancy word used to express the automatic elimination of unused code. But I think there is a solution for that, one that I won't implement since I believe the library is small enough and minified and compressed it will be very small indeed. The solution would involve separating each of the LINQ methods (or categories of methods, like first, firstOrDefault, last and lastOrDefault, for example) in different files. Then you can use only what you need and the files would attach the functions to the Enumerable prototype.

In fact, there are a lot of LINQ methods I have never had use for, stuff like intersect and except or append and prepend. It makes sense to create a core Enumerable class and then add other stuff only when required. But as I said, it's small enough to not matter. As such I separated the functionality in Typescript files that contain the basic functionality, the complete functionality and some extra functions. The Javascript result is a Linqer, a Linqer.slim, a Linqer.extra and a Linqer.all, covering the entire spectrum of needs. It would have been user unfriendly to put every little thing in its own file.

Bottom line, I hope you find this library useful or at least it inspires you as it did me when I've read the original blog post from Dan Shappir.

P.S. I am not the only one that had this idea, you might also want to look at linq.js which uses a completely different approach, using regular expressions. I think the closest to what LINQ should be is Manipula, that uses custom iterators for each operation rather than use the same class. Another possibility is linq-collections, which does the work via TypeScript, apparently. Also linq.es6... I am sure there are more examples if one looks closely. Feel free to let me know if you did or know of similar work and also please give me whatever feedback you see fit. I would like this library to be useful, not just a code example for my blog.

# Unit testing the Complementary game

I hope you at least heard of the concept of Unit Testing as it is one of the principal pillars of software development. Its purpose is to automatically check the functionality of isolated components of your code, but it adds a lot of benefits:

• your code becomes more modular - you only worry about the code you change
• your code becomes more readable - clear dependency chain and tests demonstrate in code what was the purpose of particular features
• you gain confidence that your code works as you are making changes to it - refactoring without unit tests in place is usually dangerous
• changing any component with another implementation does not affect the overall application

This post is a companion to the Programming a simple game in pure HTML and Javascript in the sense that it is that game that we will be testing. Also, as per the requirements of that project, we will not be using any of the numerous unit testing frameworks available for Javascript code.

When we left off the development of the game we had three files:

• complementary.html - the structure of the page
• complementary.css - the visual design of the page components
• complementary.js - all the code of the game, including the initialization and the game starting bit

In order to test our individual components, we need to separate them. So let's split complementary.js in four files:

• complementary.js - just the game start (instantiating Game and initializing it)
• game.js - the Game class
• color.js - the Color class
• elements.js - the custom HTML elements and their registration

Obviously the HTML will change to load all of these Javascript files. When we get to modules, this will become a non issue.

There are things that we could test on the custom HTML elements, but let's leave that aside. Also the two lines in complementary.js will not need testing. The simplest component should be the first to be tested and that is Color.

We start by creating a new HTML file (color tests.html) and we fill it with code that checks the Color class works as expected. First the code and then the discussion:

``````<html>

<script src="color.js"></script>
<script>
// this can easily be changed to display a nice report in this page
const assert ={
true:(value, message)=> {
if (value) {
console.log('Test PASSED ('+message+')');
} else {
console.warn('Test FAILED');
throw new Error(message);
}
}
};
</script>

<body>
<script>
// Arrange
const color1 = new Color(123);
const color2 = new Color(123);
const color3 = new Color(234);
// Act
const equalsWorks = color1.equals(color2);
const notEqualsWorks = !color1.equals(color3);
// Assert
assert.true(equalsWorks,'Expected two colors initialized with the same value to be equal');
assert.true(notEqualsWorks,'Expected two colors initialized with different values not to be equal');
</script>

<script>
// Arrange
const color = new Color();
const doubleInvertedColor = color.complement().complement();
// Act
const complementAndEqualsWork = color.equals(doubleInvertedColor);
// Assert
assert.true(complementAndEqualsWork,'Expected the complementary or a complementary color to be the original color');
</script>

<script>
// Arrange
const acolor = new Color(0x6789AB);
const stringColor = acolor.toString();
// Act
const toStringWorks = stringColor==='#6789ab';
// Assert
assert.true(toStringWorks,'Expected the HTML representation of the color to be #6789ab and it was '+stringColor);
</script>

</body>

</html>``````

A test should follow the AAA structure:

• Arrange - sets up the necessary items for the test to run
• instantiate classes to be tested
• mock functionality of dependencies - we will see this when we test Game
• Act - executes the code intended to be tested and acquires results
• Assert - verifies that the test results are the ones expected

Normally, a framework would take tests written in a certain way and then produce some sort of report, with nice green and red rows, with messages, with information on where errors occurred and so on. However, I intend to demonstrate the basics of unit testing, so no framework is actually needed.

A unit test:

• is a piece of code (who unit tests the unit test?!)
• it requires effort, it is just as prone to bugs as normal code and requires maintenance just like any other code (shit doesn't just happen, it takes time and effort)
• it requires infrastructure that uses it to periodically test your changes (either someone does it manually or there is some setup to run it automatically and display/email the report)

In the code above I created a script tag for each test in which I am following AAA to create Color instances and then check their functionality does what it should. A very basic assert object is handling the reporting part. It remains homework for the reader to update that part or to plug in an existing unit testing framework.

The Color class is very simple:

• it supports initializing with a color integer representing the RGB values of the color
• toString method that returns the HTML representation of the color
• complement method returns the complement of the color
• equals method checks if two colors are equal

There are no external dependencies, meaning that it needs nothing from the outside in order to work. Game, for example, requires Color, which is a dependency for Game.

Open the color tests.html file in the browser and open the development tools (F12 or Ctrl-Shift-I) and refresh the page. You should see in the console that all the tests passed. Change something in a test so it fails and it should both throw an error in the console and show you a dialog with the failing test.

Now, let's test Game. The code of the game tests.html file:

``````<html>

<script src="game.js"></script>
<script>
// this can easily be changed to display a nice report in this page
const assert ={
true:(value, message)=> {
if (value) {
console.log('Test PASSED ('+message+')');
} else {
console.warn('Test FAILED');
throw new Error(message);
}
}
};
</script>

<body>
<script>
// Arrange
const game = new Game();
// Act
// Assert
</script>

</body>

</html>``````

I used the same structure, the same assert object, only I loaded game.js instead of color.js. Then I wrote a test in which I do nothing than instantiate a Game. If you execute this page it will work just fine. No errors because we have not, in fact, executed anything. We need to execute .init(document), remember?

And now it becomes apparent why I chose to initialize the document from init instead of using window.document in my code. window.document is now the document of the test page, it has no complementary-board element in it. We haven't even defined any custom HTML elements or a Color class. In fact, we can now test that calling init with no parameter will fail:

``````    <script>
// Arrange
const game = new Game();
// Act
let anyError = null;
try {
game.init();
} catch(error) {
anyError = error;
}
// Assert
assert.true(anyError!=null,'Expected the init method of a Game class to fail if run with no parameters ('+anyError+')');
</script>``````

And, indeed, if we open the page now we get a console log like this:

``Test PASSED (Expected the init method of a Game class to fail if run with no parameters (TypeError: Cannot read property 'addEventListener' of undefined))``

You just learned another important characteristic of a unit test: it tests both what should work and what shouldn't. This is one of the reasons why unit testing is hard. For each piece of code you need to test when it works and when it fails as expected. Now we have to test how Game should work, and that means we get into mocking.

Mocking is when you replace a dependency with something that looks exactly the same, but does something else. For unit tests mock objects need to do the simplest things and those things must be predictable.

Let's see how one of these tests would look:

``````    <script>
// Arrange
const mockDoc = {
}
};
const game2 = new Game();
// Act
let anyError2 = null;
try {
game2.init(mockDoc);
} catch(error) {
anyError2 = error;
}
// Assert
assert.true(anyError2==null,'Expected the init method of a Game class to not fail if run with correct parameters ('+anyError2+')');
</script>``````

Just by providing an object with an addEventListener function, the initialization of the game now works. mockDoc is a mocked document and this is called mocking.

Let's look at how would a "happy path" test look, one that assumes everything goes correctly and moves through and entire flow:

``````    <script>
// Arrange
const mockDoc3 = {
testData : {},
this.testData.eventName = eventName;
},
getElementsByTagName:function(tagName) {
this.testData.tagName = tagName;
return [this.mockBoard];
},
mockBoard: {
setChoiceHandler:function(handler) {
this.choiceHandler=handler;
}
}
};
const game3 = new Game();
// Act
let anyError3 = null;
try {
game3.init(mockDoc3);
} catch(error) {
anyError3 = error;
}
Math = {
random:function() {
return 0.4;
},
floor:function(x) { return x; },
round:function(x) { return x; },
pow:function(x,p) { if (p==1) return x; else throw new Error('Expected 1 as the exponent, not '+p); }
};
Color = {
index:0,
new:function(value) {
return {
val: value,
equals: function(x) { return x.val==this.val; },
complement: function() { return Color.new(1000-this.val); }
};
},
random:function() {
this.index++;
return Color.new(this.index*10);
}
}
mockDoc3.mockBoard.choiceHandler(3);
// Assert
assert.true(anyError3==null,'Expected the init method of a Game class to not fail if run with correct parameters ('+anyError3+')');
assert.true(mockDoc3.testData.tagName==='complementary-board','Game is not looking for a complementary-board element');
assert.true(game3._roundData.guideColor.val === 10,'Guide color object expected to have val=10 ('+JSON.stringify(game3._roundData.guideColor)+')');
assert.true(game3._roundData.tries.size === 1,'Expected 1 unsuccessful try ('+JSON.stringify(game3._roundData.tries)+')');
assert.true(game3._roundData.tries.has(3),'Expected unsuccessful try with value of 3 ('+JSON.stringify(game3._roundData.tries)+')');
assert.true(game3._log.length === 0,'Expected no score after one unsuccessful try ('+JSON.stringify(game3._log)+')');
// Act 2 (heh!)
mockDoc3.mockBoard.choiceHandler(2);
// Assert 2
assert.true(game3._roundData.guideColor.val === 60,'Guide color object expected to have val=60 ('+JSON.stringify(game3._roundData.guideColor)+')');
assert.true(game3._roundData.tries.size === 0,'Expected no unsuccessful tries after correct response ('+JSON.stringify(game3._roundData.tries)+')');
assert.true(game3._log.length === 1,'Expected one item of score after correct answer ('+JSON.stringify(game3._log)+')');
assert.true(game3._log[0] === 50,'Expected 50 as the score after one fail and one correct answer ('+JSON.stringify(game3._log)+')');

</script>
``````

There is a lot to unpack here, including the lazy parts of the test. Here are some of the issues with it:

• it doesn't follow the AAA pattern, it asserts, then acts again, then asserts again
• while this works, it doesn't encapsulate testing of a single feature
• it is the equivalent of the classes or methods with multiple responsibilities from normal code
• the correct way to do it is to write another test, have two choiceHandler calls in the Act part and assert only that particular path
• it tests internal functionality
• in order to write the test I had to look at how the Game class works internally and then tailor the test so it works
• it accesses private data like _log and _roundData
• the Game class did not abstract all of its dependencies
• this is painfully obvious when mocking the Math object - in Javascript this is easy, but in other languages the Math functionality comes as an interface (a declaration of available members with no implementation)
• this is not a test problem, but a Game problem which makes testing tedious
• test contains logic
• look at the Math and Color mocks, how they compute values and return objects
• some values there are particularly chosen to "work"
• have you noticed how random returns 0.4 so that multiplied with 5 (number of choices) it returns 2, which then is equal with the correct choice?
• test is not independent
• Math and Color are replaced with some static objects, thus changing the environment for following tests

But it works, even if it's not very well written. Here are some of its good features:

• it tests a full game round with one bad and one good choice
• it doesn't try to go around randomness by adding more code in the assertion part
• it could have easily gone that way in order to determine the correct color in a random list, thus replicating or reverse engineering the Game logic into the test
• all the expected results are completely predictable (the score values, the indexes, etc)
• it tests only Game functionality, not others
• I could have not mocked Color, loading color.js and thus relying in a single test on functionality from a dependency

The lessons learned from this tell us that both the Game code and the test code could have been written better in regard to maintainability, with dependencies clearly declared, easy to mock or replace. In fact, the greatest gain of a company with hiring a senior developer is not on how well code works, but how much time is saved and how much risk is avoided when the code is written with separation of concerns and unit testing in mind.

It is funny, but when a piece of code is not testable, writing a single unit test forces you to refactor it into a good shape. The rest of the tests only test functionality, as the class has been rewritten with testing in mind. So that is my advice: whenever you write something, even a silly game like Complementary, write one "happy path" unit test per class.

Homework for you: rewrite the Game class and its test class so that testing becomes easier and more correct.

# Programming a simple game in pure HTML and Javascript

The code for this series of posts can be found at https://github.com/Siderite/Complementary

I was helping a friend with basic programming and I realized that I've been so caught up with the newest fads and development techniques that I've forgotten about simple programming, for fun, with just the base principles and tools provided "out of the box". This post will demonstrate me messing up writing a game using HTML and Javascript only.

## Mise en place

This French phrase is used in professional cooking to represent the preparation of ingredients and utensils before starting the actual cooking. We will need this before starting developing our game:

• description: the game will show a color and the player must choose from a selection of other colors the one that is complementary
• two colors are complementary if when they are mixed, they cancel each other out, resulting in a grayscale "color" like white, black or some shade of gray. Wait! Was that the metaphor in Fifty Shades of Grey?
• technological stack: HTML, Javascript, CSS
• flavor of Javascript: ECMAScript 2015 (also known as ES6)
• using modules: no - this would be nice, but modules obey CORS, so you won't be able to run it with the browser from the local file system.
• unit testing: yes, but we have to do it as simply as possible (no external libraries)
• development IDE: Visual Studio Code
• it's free and if you don't like it, you can just use Notepad to the same result
• source control: Git (on GitHub)

### Installing Visual Studio Code

Then, select the Open Folder option, create a project folder (let's call it Complementary), then click on Select Folder.

The vanilla installation will help you with syntax highlighting, code completion, code formatting.

### Project structure

For starters we will need the following files:

• complementary.html - the actual page that will be open by the browser
• complementary.js - the Javascript code
• complementary.css - the CSS stylesheet

Other files will be added afterwards, but this is the most basic separation of concerns: code and data in the .js file, structure in .html and presentation in .css.

## Starting to code

First, let's link the three files together by writing the simplest HTML structure:

``````<html>
<script src="complementary.js"></script>
<body>

</body>
</html>``````

This instructs the browser to load the CSS and JS files.

In the Javascript file we encapsulate out logic into a Game class:

``````"use strict";
class Game {
init(doc) {
this._document = doc;
}

}
}

const game=new Game();
game.init(document);``````

We declared a class (a new concept in Javascript ES6) and a method called init that receives a doc. The idea here is that when the script is loaded, a new Game will be created and the initialization function will receive the current document so it can interact with the user interface. We used the DOMContentLoaded event to call onLoad only when the page document object model (DOM) has been completely loaded, otherwise the script would run before the elements have been loaded.

Also, not the use of the bind method on a function. addEventListener expects a function as the event handler. If we only specify this.onLoad, it will run the function, but with the this context of the event, which would be window, not our game object. this.onLoad.bind(this), on the other hand, is a function that will be executed in the context of our game.

Now, let's consider how we want to game to play out:

• a guide color must be shown
• this means the color needs to be generated
• a list of colors to choose from must be displayed
• colors need to be generated
• one color needs to be complementary to the guide color
• color elements need to respond to mouse clicks
• a result must be computed from the chosen color
• the outcome of the user choice must be displayed
• the score will need to be calculated

This gives us the structure of the game user interface. Let's add:

• a guide element
• a choice list element
• a score element
``````<html>
<script type="module" src="complementary.js"></script>
<body>
<div id="guideColor"></div>
<div id="choiceColors"></div>
<div id="score"></div>
</body>
</html>``````

Note that we don't need to choose how they look (that's the CSS) or what they do (that's the JS).

This is a top-down approach, starting from user expectations and then filling in more and more details until it all works out.

Let's write the logic of the game. I won't discuss that too much, because it's pretty obvious and this post is about structure and development, not the game itself.

``````"use strict";
class Game {
constructor() {
// how many color choices to have
this._numberOfChoices = 5;
// the list of user scores
this._log = [];
}
init(doc) {
this._document = doc;
}
this._guide = this._document.getElementById('guideColor');
this._choices = this._document.getElementById('choiceColors');
// one click event on the parent, but event.target contains the exact element that was clicked
this._score = this._document.getElementById('score');
this.startRound();
}
startRound() {
// all game logic works with numeric data
const guideColor = this.randomColor();
this._roundData = {
guideColor: guideColor,
choiceColors: this.generateChoices(guideColor),
tries: new Set()
};
// only this method transforms the data into visuals
this.refreshUI();
}
randomColor() {
return Math.round(Math.random() * 0xFFFFFF);
}
generateChoices(guideColor) {
const complementaryColor = 0xFFFFFF - guideColor;
const index = Math.floor(Math.random() * this._numberOfChoices);
const choices = [];
for (let i = 0; i < this._numberOfChoices; i++) {
choices.push(i == index
? complementaryColor
: this.randomColor());
}
return choices;
}
refreshUI() {
this._guide.style.backgroundColor = '#' + this._roundData.guideColor.toString(16).padStart(6, '0');
while (this._choices.firstChild) {
this._choices.removeChild(this._choices.firstChild);
}
for (let i = 0; i < this._roundData.choiceColors.length; i++) {
const color = this._roundData.choiceColors[i];
const elem = this._document.createElement('span');
elem.style.backgroundColor = '#' + color.toString(16).padStart(6, '0');
elem.setAttribute('data-index', i);
this._choices.appendChild(elem);
}
while (this._score.firstChild) {
this._score.removeChild(this._score.firstChild);
}
const threshold = 50;
for (let i = this._log.length - 1; i >= 0; i--) {
const value = this._log[i];
const elem = this._document.createElement('span');

elem.className = value >= threshold
? 'good'
elem.innerText = value;
this._score.appendChild(elem);
}
}
onChoiceClick(ev) {
const elem = ev.target;
const index = elem.getAttribute('data-index');
// just a regular expression test that the attribute value is actually a number
if (!/^\d+\$/.test(index)) {
return;
}
const result = this.score(+index);
elem.setAttribute('data-result', result);
}
score(index) {
const expectedColor = 0xFFFFFF - this._roundData.guideColor;
const isCorrect = this._roundData.choiceColors[index] == expectedColor;
if (!isCorrect) {
}
if (isCorrect || this._roundData.tries.size >= this._numberOfChoices - 1) {
const score = 1 / Math.pow(2, this._roundData.tries.size);
this._log.push(Math.round(100 * score));
this.startRound();
}
return isCorrect;
}
}

const game = new Game();
game.init(document);``````

This works, but it has several problems, including having too many responsibilities (display, logic, handling clicks, generating color strings from numbers, etc).

And while we have the logic and the structure, the display leaves a lot to be desired. Let's fix this first (I am terrible with design, so I will just dump the result here and it will be a homework for the reader to improve on the visuals).

First, I will add a new div to contain the three others. I could work directly with body, but it would be ugly:

``````<html>

<script src="complementary.js"></script>

<body>
<div class="board">
<div id="guideColor"></div>
<div id="choiceColors"></div>
<div id="score"></div>
</div>
</body>

</html>``````

Then, let's fill in the CSS:

``````body {
width: 100vw;
height: 100vh;
margin: 0;
}
.board {
width:100%;
height:100%;
display: grid;
grid-template-columns: 50% 50%;
grid-template-rows: min-content auto;
}
#score {
grid-column-start: 1;
grid-column-end: 3;
grid-row: 1;
display: flex;
flex-direction: row;
flex-wrap: nowrap;
}
#score span {
display: inline-block;
background-color: darkgray;
margin-left: 2px;
}
#score span.good {
background-color: darkgreen;
}
background-color: red;
}
#guideColor {
grid-column: 1;
grid-row: 2;
}
#choiceColors {
grid-column: 2;
grid-row: 2;
display: flex;
flex-direction: column;
}
#choiceColors span {
flex-grow: 1;
cursor: pointer;
}
#choiceColors span[data-result=false] {
opacity: 0.3;
}``````

I used a lot of flex and grid to display things.

The game should now do the following:

• displays a left side color
• displays five rows of different colors in the right side
• clicking on any of them modifies the score (each wrong choice halves the maximum score of 100)
• when there are no more moves left or the correct choice is clicked, the score is added to a list at the top of the board
• the score tiles are either green (score>=50) or red

However, I am dissatisfied with the Javascript code. If Game has too many responsibilities it is a sign that new classes need to be created.

### Refactoring the code

First, I will encapsulate all color logic into a Color class.

``````class Color {
constructor(value = 0  /* black */) {
this._value = value;
}
toString() {
}
complement() {
return new Color(0xFFFFFF - this._value);
}
equals(anotherColor) {
return this._value === anotherColor._value;
}
static random() {
return new Color(Math.round(Math.random() * 0xFFFFFF));
}
}``````

This simplifies the Game class like this:

``````class Game {
constructor() {
// how many color choices to have
this._numberOfChoices = 5;
// the list of user scores
this._log = [];
}
init(doc) {
this._document = doc;
}
this._guide = this._document.getElementById('guideColor');
this._choices = this._document.getElementById('choiceColors');
// one click event on the parent, but event.target contains the exact element that was clicked
this._score = this._document.getElementById('score');
this.startRound();
}
startRound() {
// all game logic works with numeric data
const guideColor = Color.random();
this._roundData = {
guideColor: guideColor,
choiceColors: this.generateChoices(guideColor),
tries: new Set()
};
// only this method transforms the data into visuals
this.refreshUI();
}
generateChoices(guideColor) {
const complementaryColor = guideColor.complement();
const index = Math.floor(Math.random() * this._numberOfChoices);
const choices = [];
for (let i = 0; i < this._numberOfChoices; i++) {
choices.push(i == index
? complementaryColor
: Color.random());
}
return choices;
}
refreshUI() {
this._guide.style.backgroundColor = this._roundData.guideColor.toString();
while (this._choices.firstChild) {
this._choices.removeChild(this._choices.firstChild);
}
for (let i = 0; i < this._roundData.choiceColors.length; i++) {
const color = this._roundData.choiceColors[i];
const elem = this._document.createElement('span');
elem.style.backgroundColor = color.toString();
elem.setAttribute('data-index', i);
this._choices.appendChild(elem);
}
while (this._score.firstChild) {
this._score.removeChild(this._score.firstChild);
}
const threshold = 50;
for (let i = this._log.length - 1; i >= 0; i--) {
const value = this._log[i];
const elem = this._document.createElement('span');

elem.className = value >= threshold
? 'good'
elem.innerText = value;
this._score.appendChild(elem);
}
}
onChoiceClick(ev) {
const elem = ev.target;
const index = elem.getAttribute('data-index');
// just a regular expression test that the attribute value is actually a number
if (!/^\d+\$/.test(index)) {
return;
}
const result = this.score(+index);
elem.setAttribute('data-result', result);
}
score(index) {
const expectedColor = this._roundData.guideColor.complement();
const isCorrect = this._roundData.choiceColors[index].equals(expectedColor);
if (!isCorrect) {
}
if (isCorrect || this._roundData.tries.size >= this._numberOfChoices - 1) {
const score = 1 / Math.pow(2, this._roundData.tries.size);
this._log.push(Math.round(100 * score));
this.startRound();
}
return isCorrect;
}
}``````

But it's still not enough. Game is still doing a lot of UI stuff. Can we fix that? Yes, with custom HTML elements!

Here is the code. It looks verbose, but what it does is completely encapsulate UI logic into UI elements:

``````class GuideColor extends HTMLElement {
set color(value) {
this.style.backgroundColor = value.toString();
}
}

class ChoiceColors extends HTMLElement {
connectedCallback() {
this._clickHandler = this.onChoiceClick.bind(this);
}
disconnectedCallback() {
this.removeEventListener('click', this._clickHandler, false);
}
onChoiceClick(ev) {
const elem = ev.target;
if (!(elem instanceof ChoiceColor)) {
return;
}
const result = this._choiceHandler(elem.choiceIndex);
elem.choiceResult = result;
}
setChoiceHandler(handler) {
this._choiceHandler = handler;
}
set colors(value) {
while (this.firstChild) {
this.removeChild(this.firstChild);
}
for (let i = 0; i < value.length; i++) {
const color = value[i];
const elem = new ChoiceColor(color, i);
this.appendChild(elem);
}
}
}

class ChoiceColor extends HTMLElement {
constructor(color, index) {
super();
this.color = color;
this.choiceIndex = index;
}
get choiceIndex() {
return +this.getAttribute('data-index');
}
set choiceIndex(value) {
this.setAttribute('data-index', value);
}
set choiceResult(value) {
this.setAttribute('data-result', value);
}
set color(value) {
this.style.backgroundColor = value.toString();
}
}

class Scores extends HTMLElement {
set scores(log) {
while (this.firstChild) {
this.removeChild(this.firstChild);
}
for (let i = log.length - 1; i >= 0; i--) {
const value = log[i];
const elem = new Score(value);
this.appendChild(elem);
}
}
}

class Score extends HTMLElement {
constructor(value) {
super();
this.innerText = value;
this.className = value > 50
? 'good'
}
}

class Board extends HTMLElement {
constructor() {
super();
this._guide = new GuideColor();
this._choices = new ChoiceColors();
this._score = new Scores();
}
connectedCallback() {
this.appendChild(this._guide);
this.appendChild(this._choices);
this.appendChild(this._score);
}
setChoiceHandler(handler) {
this._choices.setChoiceHandler(handler);
}
set guideColor(value) {
this._guide.color = value;
}
set choiceColors(value) {
this._choices.colors = value;
}
set scores(value) {
this._score.scores = value;
}
}

window.customElements.define('complementary-board', Board);
window.customElements.define('complementary-guide-color', GuideColor);
window.customElements.define('complementary-choice-colors', ChoiceColors);
window.customElements.define('complementary-choice-color', ChoiceColor);
window.customElements.define('complementary-scores', Scores);
window.customElements.define('complementary-score', Score);``````

With this, the HTML becomes:

``````<html>

<script src="complementary.js"></script>

<body>
<complementary-board>
</complementary-board>
</html>``````

and the CSS:

``````body {
width: 100vw;
height: 100vh;
margin: 0;
}
complementary-board {
width:100%;
height:100%;
display: grid;
grid-template-columns: 50% 50%;
grid-template-rows: min-content auto;
}
complementary-scores {
grid-column-start: 1;
grid-column-end: 3;
grid-row: 1;
display: flex;
flex-direction: row;
flex-wrap: nowrap;
}
complementary-score {
display: inline-block;
background-color: darkgray;
margin-left: 2px;
}
complementary-score.good {
background-color: darkgreen;
}
background-color: red;
}
complementary-guide-color {
grid-column: 1;
grid-row: 2;
}
complementary-choice-colors {
grid-column: 2;
grid-row: 2;
display: flex;
flex-direction: column;
}
complementary-choice-color {
flex-grow: 1;
cursor: pointer;
}
complementary-choice-color[data-result=false] {
opacity: 0.3;
}``````

## Next

In the next blog posts we will see how we can test our code (we have to make it more testable first!) and how we can use Git as source control. Finally we should have a working game that can be easily modified independently: the visual design, the working code, the structural elements.

# FizzBuzz for the next generation

FizzBuzz is a programming task that is often used for job interviews, because it shows the thinking of the candidate in an isolated and concrete case. The requirements may vary slightly, but is goes like this: A loop is going through numbers from 1 to 100. The candidate must write the code in the loop that will display, for each number, a string. This string is: "Fizz" for numbers divisible by 3, "Buzz" divisible by 5 and "FizzBuzz" for numbers that are both divisible by 3 and 5. For all other numbers, just display that number.

There have been many implementations of this, for example my own in JavaScript from a while ago and FizzBuzz Enterprise Edition, which is always a good read about how not to complicate your code. However, since I've last written about it, JavaScript has changed, so I felt compelled to write an updated version. And here it is:
`(d=n=>('0369'.includes((f=n=>n>9&&f([...''+n].reduce((s,v)=>+v+s,0))||n)&&f(n))&&'Fizz'||'')+(/[05]\$/.test(n)&&'Buzz'||'')||n)*(i=n=>n>100||console.log(n+': '+d(n))+i(n+1))*i(1)`

Among the abominations there, some of them inspired by C++ because why not, there are some of the new JavaScript constructs, like arrow functions and the spread operator. I know it seems pointless, but it's not: try to understand what the code does. If you want to see it in action, open Dev Tools in any browser and copy paste it in the console.

# JSON.stringify with circular references and nicely indented

Sometimes you want to display a Javascript object as a string and when you use JSON.stringify you get an error: Converting circular structure to JSON. The solution is to use a function that keeps a record of objects found and returns a text explaining where the circular reference appeared. Here is a simple function like that:
`function fixCircularReferences() {  const defs={};  return (k,v) => {    const def = defs[v];    if (def && typeof(v) == 'object') return '['+k+' is the same as '+def+']';    defs[v]=k;    return v;  }}`

And the usage is
`JSON.stringify(someObject,fixCircularReferences(),2);`
. If you want to use it as a JSON (so serialize the object for real), replace the return of a string with
`return null`
, although that means you have not properly serialized the initial object.

The function is something I cropped up in a minute or so. If there are some edge cases where it didn't work, let me know and I will update it.

# Javascript ES6 way to update object properties: Object.assign

How many times did you find some code that looked like this:
`// previous codelet someValue1 = 'something';let someValue2 = 'something else';let someValue3 = 'something blue';let someValue4 = 'something entirely different and original'; // our codeconst parentObject=new ParentObject();parentObject.childObject.someValue1=someValue1;parentObject.childObject.someValue2=someValue2;parentObject.childObject.someValue3=someValue3;parentObject.childObject.someValue4=someValue4;`
and you really wanted to make it look nicer? Well now you can! Introducing the ECMAScript 6 Object.assign method.

And thanks to some other features of ES6, we can write the same code like this:
`// our codeconst parentObject=new ParentObject();Object.assign(parentObject.childObject,{someValue1, someValue2, someValue3, someValue4});`

Note that { someVariable } is equivalent to the ES5 { someVariable: someVariable } notation.

# ECMAScript/Typescript gotcha: Map has to be used with set/get not like a Dictionary in .NET

In ECMAScript 6 there is a Map class that looks and feels like a .NET Dictionary. As an extension of JavaScript, TypeScript code like this is totally valid:
`let map:Map<number,string> = new Map<number,string>();map[1]="Category One";let name:string = map[1]; //name is now "Category One"`

However, the code above is wrong. What this does is create a string property named "1" on the map object with a value "Category One". Its "size" is 0. The correct code would be like this:
`let map:Map<number,string> = new Map<number,string>();map.set(1,"Category One");let name:string = map.get(1); //name is now "Category One", map.size is 1`

Similar code for ECMAScript 6, you can just declare the map as let map = new Map();

Just in case you wonder why utilize this hard to use type instead of a normal object, it's a user choice. Most of the pros involve the type of the key (object keys can only be strings or symbols) and ease of counting and iterating, but these issues can be solved trivially in code, if ever needed.

# Powerful features in Javascript ES2015: enforcing required parameters

I just read a very cool article (Understanding Default Parameters in Javascript) and my takeaway is this smart piece of code to enforce that a parameter is specified:
`const isRequired = () => { throw new Error('param is required'); };function filterEvil(array, evil = isRequired()) {  return array.filter(item => item !== evil);   }`

So all you have to do is define the isRequired function in a shared library file and then use it in any function that you write.

Are you a bit put off by the fact you can use functions as default parameters? Welcome to Javascript, a language that seems designed by Eurythmics

# Careful with case sensitivity in html files. (especially in Firefox extensions)

After my disappointment with the Firefox for Android lack of proper bookmarks API implementation, I was at least happy that my Bookmark Explorer extension works well with Firefox for desktop. That quickly turned cold when I got a one star review because the extension did not work. And the user was right, it didn't! One of the variables declared in one of the Javascript files was not found. But that only happened in the published version, not the unpacked one on my computer.

1. Load unpacked (from my computer) extension
2. Test it
3. Works great
4. Make it a Zip file and publish it
5. Shame! Shame! Shame!

Long story short, I was loading the Javascript file like this: <script src="ApiWrapper.js"></script> when the name of the file was apiWrapper.js (note the lowercase A). My computer file system is Windows, couldn't care less about filename casing, while the virtual Zip filesystem probably isn't like that, at least in Firefox's implementation. Note that this error only affected Firefox and not Chrome or (as far as I know - because it has been 2 months since I've submitted the extension and I got no reply other than "awaiting moderation") Opera.

# Get the distinct values of an array in Javascript ES6

I've found a small gem in Javascript ES6 that I wanted to share:
`let arr = [3, 5, 2, 2, 5, 5];let unique = [...new Set(arr)]; // [3, 5, 2]`

# Ienumerable and yield return in C#... and in Javascript!? Iterators and generators

### IEnumerable/IEnumerator - the iterator design pattern implemented in the C# language

C# started up with the IEnumerable interface, which exposed one method called GetEnumerator. This method would return a specialized object (implementing IEnumerator) that could give you from a collection of items the current item and could also advance. Unlike Java on which C# is originally based, this interface was inherited by even the basest of collection objects, like arrays. This allowed a special construct in the language: foreach. One uses it very simply:
`for (var item in ienumerable) // do something`
. No need to know how or from where the item is exactly retrieved from the collection, just get the first, then the next and so on until there are no more items.

In .NET 2.0 generics came, along their own interfaces like IEnumerable<T>, holding items of a specific type, but the logic is the same. It also introduced another language element called yield. One didn't need to write an IEnumerator implementation anymore, they could just define a method that returned an IEnumerable and inside "yield return" values. Something like this:
`public class Program{    public static void Main(string[] args)    {        var enumerator = Fibonacci().GetEnumerator();        for (var i = 0; enumerator.MoveNext() && i < 10; i++)        {            var v = enumerator.Current;            Console.WriteLine(v);        }        Console.ReadKey();    }    public static IEnumerable<int> Fibonacci()    {        var i1 = 0;        var i2 = 1;        while (true)        {            yield return i2;            i2 += i1;            i1 = i2 - i1;        }    }}`

This looks a bit weird. A method is running a while(true) loop with no breaks. Shouldn't it block the execution of the program? No, because of the yield construct. While the Fibonacci series is infinite, we would only get the first 10 values. You can also see how the enumerator works, when used explicitly.

### Iterators and generators in Javascript ES6

EcmaScript version 6 (or ES6 or ES2015) introduced the same concepts in Javascript. An iterator is just an object that has a next() method, returning an object containing the value and done properties. If done is true, value is disregarded and the iteration stops, if not, value holds the current value. An iterable object will have a method that returns an iterator, the method's name being Symbol.iterator. The for...of construct of the language iterates the iterable. String, Array, TypedArray, Map and Set are all built-in iterables, because the prototype objects of them all have a Symbol.iterator method. Example:
`var iterable=[1,2,3,4,5];for (v of iterable) {    console.log(v);}`

But what about generating values? Well, let's do it using the knowledge we already have:
`var iterator={    i1:0,    i2:1,    next:function() {        var result = { value: this.i2 }        this.i2+=this.i1;        this.i1=this.i2-this.i1;        return result;    }};var iterable = {};iterable[Symbol.iterator]=() => iterator;var iterator=iterable[Symbol.iterator]();for (var i=0; i<10; i++) {    var v=iterator.next();    console.log(v.value);}`

As you can see, it is the equivalent of the Fibonacci code written in C#, but look at how unwieldy it is. Enter generators, a feature that allows, just like in C#, to define functions that generate values and the iterable associated with them:
`function* Fibonacci() {    var i1=0;    var i2=1;    while(true) {        yield i2;        i2+=i1;        i1=i2-i1;    }}var iterable=Fibonacci();var iterator=iterable[Symbol.iterator]();for (var i=0; i<10; i++) {    var v=iterator.next();    console.log(v.value);}`

No, that's not a C pointer, thank The Architect, it's the way Javascript ES6 defines generators. Same code, much clearer, very similar to the C# version.

### Uses

OK, so these are great for mathematics enthusiasts, but what are we, regular dudes, going to do with iterators and generators? I mean, for better or for worse we already have for and .forEach in Javascript, what do we need for..of for? (pardon the pun) And what do generators help with?

Well, in truth, one could get away simply without for..of. The only object where .forEach works differently is the Map object, where it returns only the values, as different from for..of which returns arrays of [key,value]. However, considering generators are new, I would expect using for..of with them to be more clear in code and more inline with what foreach does in C#.

Generators have the ability to easily define series that may be infinite or of items which are expensive resources to get. Imagine a download of a large file where each chunk is a generated item. An interesting use scenario is when the .next function is used with parameters. This is Javascript, so an iterator having a .next method only means it has to be named like that. You can pass an arbitrary number of parameters. So here it is, a generator that not only dumbly spews out values, but also takes inputs in order to do so.

In order to thoroughly explore the value of iterators and generators I will use my extensive knowledge in googling the Internet and present you with this very nice article: The Hidden Power of ES6 Generators: Observable Async Flow Control which touches on many other concepts like async/await (oh, yeah, that should be another interesting C# steal), observables and others that are beyond the scope of this article.

I hope you liked this short intro into these interesting new features in ES6.

# Difference between "var f = function" and "function f" in Javascript

Can you tell me what is the difference between these to pieces of code?
`var f=function() {  alert('f u!');}function f() {  alert('f u!');}`

It's only one I can think of and with good code hygiene it is one that should never matter. It is related to 'hoisting', or the idea that in Javascript a variable declaration is hoisted to the top of the function or scope before execution. In other words, I can see there is a function f before the declarations above. And now the difference: 'var f = function' will have its declaration hoisted, but not its definition. f will exist at the beginning of the scope, but it will be undefined; the 'function f' format will have both declaration and definition hoisted, so that at the beginning of the scope you will have available the function for execution.

# Promises in Javascript

### Intro

I am not the authoritative person to go to for Javascript Promises, but I've used them extensively (pardon the pun) in Bookmark Explorer, my Chrome extension. In short, they are a way to handle methods that return asynchronously or that for whatever reason need to be chained. There are other ways to do that, for example using Reactive Extensions, which are newer and in my opinion better, but Rx's scope is larger and that is another story altogether.

### Learning by examples

Let's take a classic and very used example: AJAX calls. The Javascript could look like this:
`function get(url, success, error) {    var xhttp = new XMLHttpRequest();    xhttp.onreadystatechange = function () {        if (this.readyState == 4) {            if (this.status == 200) {                success(this.response);            } else {                error(this.status);            }        }    };    xhttp.open("GET", url, true);    xhttp.send();}get('/users',function(users) {    //do something with user data},function(status) {    alert('error getting users: '+status);})`

It's a stupid example and not by far complete, but it shows a way to encapsulate an AJAX call into a function that receives an URL, a handler for success and one for error. Now let's complicate things a bit. I want to get the users, then for each active user I want to get the document list, then return the ones that contain a string. For simplicity's sake, let's assume I have methods that do all that and receive a success and an error handler:
`var search = 'some text';var result = [];getUsers(function (users) {    users    .filter(function (user) {        return user.isActive();    })    .forEach(function (user) {        getDocuments(user, function (documents) {            result = result.concat(documents.filter(function (doc) {                        return doc.text.includes(text);                    }));        }, function (error) {            alert('Error getting documents for user ' + user + ': ' + error);        });    });}, function (error) {    alert('Error getting users: ' + error);});`

It's already looking wonky. Ignore the arrow anti pattern, there are worse issues. One is that you never know when the result is complete. Each call for user documents takes an indeterminate amount of time. This async programming is killing us, isn't it? We would have much better liked to do something like this instead:
`var result = [];var search = 'some text';var users = getUsers();users.filter(function (user) {    return user.isActive();}).forEach(function (user) {    var documents = getDocuments(user);    result = result.concat(documents.filter(function (doc) {                return doc.text.includes(text);            }));});`
First of all, no async, everything is deterministic and if the function for getting users or documents fails, well, it can handle itself. When this piece of code ends, the result variable holds all information you wanted. But it would have been slow, linear and simply impossible in Javascript, which doesn't even have a Pause/Sleep option to wait for stuff.

Now I will write the same code with methods that use Promises, then proceed on explaining how that would work.
`var result = [];var search = 'some text';var userPromise = getUsers();userPromise.then(function (users) {    var documentPromises = users        .filter(function (user) {            return user.isActive();        })        .map(function (user) {            return getDocuments(user);        });    var documentPromise = Promise.all(documentPromises);    documentPromise    .then(function (documentsArray) {        documentsArray.forEach(function (documents) {            result = result.concat(documents.filter(function (doc) {                        return doc.text.includes(search);                    });        });        // here the result is complete    })    .catch (function (reason) {        alert('Error getting documents:' + reason);    });});`
Looks more complicated, but that's mostly because I added some extra variables for clarity.

The first thing to note is that the format of the functions doesn't look like the async callback version, but like the synchronous version: var userPromise=getUsers();. It doesn't return users, though, it returns the promise of users. It's like a politician function. This Promise object encapsulates the responsibility of announcing when the result is actually available (the .then(function) method) or when the operation failed (the .catch(function) method). Now you can pass that object around and still use its result (successful or not) when available at whatever level of the code you want it.

At the end I used Promise.all which handles all that uncertainty we were annoyed about. Not only does it publish an array of all the document getting operations, but the order of the items in the array is the same as the order of the original promises array, regardless of the time it took to execute any of them. Even more, if any of the operations fails, this aggregate Promise will immediately exit with the failure reason.

To exemplify the advantages of using such a pattern, let's assume that getting the users sometimes fails due to network errors. The Internet is not the best in the world where the user of the program may be, so you want to not fail immediately, instead retry the operation a few times before you do. Here is how a getUsersWithRetry would look:
`function getUserWithRetry(times, spacing) {    var promise = new Promise(function (resolve, reject) {            var f = function () {                getUsers()                .then(resolve)                .catch (function (reason) {                    if (times <= 0) {                        reject(reason);                    } else {                        times--;                        setTimeout(f, spacing);                    }                });            }            f();        });    return promise;}`

What happens here? First of all, like all the get* methods we used so far, we need to return a Promise object. To construct one we give it as a parameter a function that receives two other functions: resolve and reject. Resolve will be used when we have the value, reject will be used when we fail getting it. We then create a function so that it can call itself and in it, we call getUsers. Now, if the operation succeeds, we will just call resolve with the value we received. The operation would function exactly like getUsers. However, when it fails, it checks the number of times it must retry and only fails (calling reject) when that number is zero. If it still has retries, it calls the f function we defined, with a timeout defined in the parameters. We finally call the f function just once.

Here is another example, something like the original get function, but that returns a Promise:
`function get(url) {  // Return a new promise.  return new Promise(function(resolve, reject) {    // Do the usual XHR stuff    var req = new XMLHttpRequest();    req.open('GET', url);    req.onload = function() {      // This is called even on 404 etc      // so check the status      if (req.status == 200) {        // Resolve the promise with the response text        resolve(req.response);      }      else {        // Otherwise reject with the status text        // which will hopefully be a meaningful error        reject(Error(req.statusText));      }    };    // Handle network errors    req.onerror = function() {      reject(Error("Network Error"));    };    // Make the request    req.send();  });}`
Copied it like a lazy programmer from JavaScript Promises: an Introduction.

### Notes

An interesting thing to remember is that the .then() method also returns a Promise, so one can do stuff like get('/users').then(JSON.parse).then(function(users) { ... }). If the function called by .then() is returning a Promise, then that is what .then() will return, allowing for stuff like someOperation().then(someOtherOperation).catch(errorForFirstOperation).then(handlerForSecondOperation). There is a lot more about promises in the Introduction in the link above and I won't copy/paste it here.

The nice thing about Promises is that they have been around in the Javascript world since forever in various libraries, but only recently as native Javascript objects. They have reached a maturity that was tested through the various implementations that led to the one accepted today by the major browsers.

Promises solve some of the problems in constructing a flow of asynchronous operations. They make the code cleaner and get rid of so many ugly extra callback parameters that many frameworks used us to. This flexibility is possible because in Javascript functions are first class members, meaning they can be passed around and manipulated just like any other parameter type.

The disadvantages are more subtle. Some parts of your code will be synchronous in nature. You will have stuff like a=sum(b,c); in functions that return values. Suddenly, functions don't return actual values, but promised values. The time they take to execute is also unclear. Everything is in flux.

### Conclusion

I hope this has opened your eyes to the possibilities of writing your code in a way that is both more readable and easy to encapsulate. Promises are not limited to Javascript, many other languages have their own implementations. As I was saying in the intro, I feel like Promises are a simple subcase of Reactive Extensions streams in the sense that they act like data providers, but are limited to only one possible result. However, this simplicity may be more easy to implement and understand when this is the only scenario that needs to be handled.