Add README files for idiomatic patterns

Author: Badacadabra

GoF/idiomatic/Behavioral/ChainOfResponsibility/README.md

@@ -0,0 +1,21 @@
+# Synopsis
+
+Imagine a long relay race with athletes from different sports. This race could involve several teams composed each time of a racewalker, a runner and a swimmer.
+
+# Problem
+
+Each sport has its own rules and each athlete will participate differently. So we cannot just evaluate the role of each athlete in the same way, even though the objective is the same for everyone within a team: the gold medal. A swimmer and a runner are both athletes, but a swimmer swims whereas a runner runs... Here we could say that each team member handles a part of the initial request which is to win the race.
+
+Moreover, this is a relay race, not an individual one. Each athlete must know the next relay where another athlete will wait for the baton before to start.
+
+# Solution
+
+Everytime a request should be handled by multiple (and complementary) processing units, the Chain of Responsibility pattern seems ideal. In this case, we can represent each athlete with a simple object literal. We will have:
+
+  * An object literal representing a walker
+  * An object literal representing a runner
+  * An object literal representing a swimmer
+
+Each of these objects should have at least their own method ("go") whose action will be specific to the associated sport. But each of these particular "go" methods will also transfer some work to the next relay, chosen by the client code.
+
+N.B. This design pattern should not be confused with simple method chaining in JavaScript.

GoF/idiomatic/Behavioral/Command/README.md

@@ -0,0 +1,24 @@
+# Synopsis
+
+I am hungry and I decide to call the nearest Tex-Mex restaurant to place an order. I hope I will receive my meal fast.
+
+# Problem
+
+Placing an order is easy to do. As a customer, you only need to say what you want to eat and nothing else. However, for the restaurant, there is a true organization behind the scenes to effectively treat your order. The chef cooks for you, then the meal is packaged and finally the delivery man brings it to you as fast as possible. Plus, you are not the only one to be hungry... The restaurant is most likely in a situation where it has to handle many orders, especially when it is time for dinner.
+
+In computer science terms, it seems obvious that the restaurant has to handle a queue of orders and that each customer is a unique entity. Since a customer normally pays his order to the delivery man, the payment should be the last step of the process. But this is not so intuitive if you try to find a good code organization for this. On the one hand, all orders are handled by the restaurant and everything required to prepare these orders is like encapsulated in each order. On the other hand, only customers can validate orders since their responsible for payment.
+
+# Solution
+
+The Command pattern is a great help here. In this pattern terminology, we will say that:
+  ***
+  * The restaurant is the "invoker" who creates and handles new orders internally.
+  * The order is the "command", in other words the request which comes from a client.
+  * The customer is the "receiver" of the order.
+
+To implement this pattern, we then need three object literals to represent each entity:
+  
+  * The customer has only one method ("pay").
+  * The order has a reference to a given customer and makes him pay using its "deliver" method.
+  * The restaurant is a more complex object with a collection (array) of orders and an essential method ("prepareOrders") that start the delivery of each order.
+

GoF/idiomatic/Behavioral/Interpreter/README.md

@@ -0,0 +1,16 @@
+# Synopsis
+
+I love music and I want to be able to analyze some compositions like "Moonlight Sonata" by Beethoven.
+
+# Problem
+
+Music is a beautiful but complex universe, and listening to music does not mean understanding it. To analyze compositions, music theory is an absolute necessity. Since music is a language, pretty much like English or French are, it has its own grammar. Understanding this grammar makes it possible to understand a composition. But here the question is: how do we describe a grammar with a programming language?
+
+# Solution
+
+The Interpreter pattern is exactly what we need to tell JavaScript how to interpret music grammar. Here we can have:
+
+  * Factory functions to create expressions (especially notes and arpeggios)
+  * A basic object literal to represent the context (the sonata)
+
+The distinction between terminal and nonterminal expressions in the Interpreter pattern is a bit like the distinction between simple and composed elements in the Composite pattern. A note is a terminal expression because it is an "elementary symbol" of the grammar. However, an arpeggio is a nonterminal expression because it can be considered as a group of notes.

GoF/idiomatic/Behavioral/Iterator/README.md

@@ -0,0 +1,18 @@
+# Synopsis
+
+I am at the library and I would like to see the list of all available books.
+
+# Problem
+
+There is generally a huge amount of books in a library, so it is great to have a catalog that allows you to have a quick overview of all available references. This catalog may be a bit special and could contain a one-page presentation for each book.
+
+In Javascript, we could use a simple loop to get the list of all books. But in fact, this would not be so convenient because each data structure and entity may have its own particularities when it comes to iteration. For instance, we know we cannot iterate through an array literal like we iterate through an object literal (array-like objects could be considered as an exception). Therefore this is generally a good idea to simplify the work to iterate through a collection...
+
+# Solution
+
+Iterator is the design pattern we need for this. To implement this pattern, we could have:
+
+  * An object literal containing an index property and at least a method named "next"
+  * A very basic object literal representing a library (which is a collection of books) 
+
+In this particular case, a collection is an iterable object whereas a catalog is an iterator object.

GoF/idiomatic/Behavioral/Mediator/README.md

@@ -0,0 +1,18 @@
+# Synopsis
+
+Tom and Dick are neighbors. Dick makes a lot of noise on Sunday mornings, which drives Tom crazy. Communication has become difficult between them because of this.
+
+# Problem
+
+If Tom and Dick cannot talk to each other directly, Dick will continue to make noise and Tom will get angry every Sunday.
+
+# Solution
+
+When communication is difficult between two objects or in a system (here the neighborhood), the solution is delegation to a third-party object. This object will make communication easier between all other objects.
+
+This is exactly the solution proposed by the Mediator pattern. To implement this pattern, we need:
+
+  * Object literals to represent Tom and Dick (who are neighbors)
+  * An object literal to represent Harry (who is the mediator)
+
+Tom and Dick have both a "send" and "receive" methods, but they do not communicate directly. They communicate through the mediator who acts a bit like a router. Thus, Harry must have a reference to both neighbor objects and, depending on the sender, he will know the receiver... 

GoF/idiomatic/Behavioral/Memento/README.md

@@ -0,0 +1,16 @@
+# Synopsis
+
+I found an interesting article on the Web and I would like to save it in my browser for later reading. For some reasons, I always use private browsing.
+
+# Problem
+
+With private browsing, history is not kept by the browser. Of course we can use back and forward buttons to navigate in the current history during the browsing session, but with this technique, it would not be possible to identify easily our favorite webpages. Furthermore, interesting webpages would not be there anymore if we close the browser and open it again.
+
+# Solution
+
+Here we have to use bookmarks to save interesting webpages and the Memento pattern allows us to simulate that behavior. We can implement this pattern using: 
+
+  * An object literal with a "saveCurrentPage" method to represent the browser (this is the "originator")
+  * An object literal containing a collection (array) of bookmarks (this is the "caretaker")
+
+When the "saveCurrentPage" method is called, a new bookmark (memento) is created and this one can be stored by the bookmarks manager.

GoF/idiomatic/Behavioral/Observer/README.md

@@ -0,0 +1,18 @@
+# Synopsis
+
+In the savanna, there are predators like lions or crocodiles and there are preys like gazelles. So lions and crocodiles often attack gazelles.
+
+# Problem
+
+Lions and crocodiles do not attack at any moment. A lion will generally attack if a gazelle is a bit too far from the herd. A crocodile will generally attack if a gazelle is a bit too close to water, especially for drinking.
+
+In programming terms, predators execute some action when a specific event occurs on the preys side. This implies the implementation of an event-handling mechanism in the code, which may be unclear if it is not properly done.
+
+# Solution
+
+The Observer design pattern helps a lot when we have to implement an event-driven system like this. Here this pattern is composed of:
+
+  * Object literals to represent different kinds of observers
+  * An object literal to represent the observable entity 
+
+The observable object (gazelle) maintains a list (array) of predators. Then, depending on its actions (determined by the client code), its "notifyPredators" method may be called. This method would iterate through the array of predators and make them attack.

GoF/idiomatic/Behavioral/State/README.md

@@ -0,0 +1,16 @@
+# Synopsis
+
+On any computer, I can see a power button. Generally, when the button is pressed while the computer is off, the computer is turned on. And when the button is pressed while the computer is on, the computer is turned off.
+
+# Problem
+
+A computer has two basic states: on and off. So when you press the power button, the system must be smart enough to understand when the computer is on and when it is off. It should also be smart enough to change its own state when the button is pressed.
+
+# Solution
+
+The State design pattern is obviously what we should use here. We need: 
+
+  * An object literal to represent the context (the PC)
+  * Object literals to represent available states (on/off)
+
+Contrary to the Strategy pattern, we can access the context directly from available states (our PC is used as a parameter of the main method of both states). This allows state changes from states themselves.

GoF/idiomatic/Behavioral/Strategy/README.md

@@ -0,0 +1,17 @@
+# Synopsis
+
+I am playing a fighting game and I do not know my opponent. Should I prefer an offensive or defensive style? 
+
+# Problem
+
+Since the opponent is unknown, the player has to choose a fighting strategy on the fly.
+In programming terms, we can say that an algorithm has to be selected at runtime, among several available algorithms.
+
+# Solution
+
+The Strategy design pattern is exactly what we need in this kind of situation. To implement this pattern, we can have:
+
+  * An object literal to represent the context (the fighting game)
+  * Object literals to represent available strategies (offense and defense)
+
+Offensive and defensive strategies seem to share a "fight" method, but the performed action is obviously different. Moreover, the context (fighting game) must have a reference to the current strategy because its main method ("play") is directly influenced by the selected strategy in the client code.

GoF/idiomatic/Behavioral/Template/README.md

@@ -0,0 +1,18 @@
+# Synopsis
+
+I am a construction professional and I always respect the basic principles of my job. I build houses and buildings following the common sense.
+
+# Problem
+
+Building something like a house is not trivial. It is very technical and, if you are not a construction professional, you may do things in the wrong order. For example, you could be tempted to build walls on a ground that is not fully prepared, leading to weak foundations.
+
+# Solution
+
+Even for professionals, it is good to have a template (like a plan drawn by an architect). This template makes it clear that you have to work on foundations first, then build walls and finally put the roof.
+
+The Template design pattern is an ideal candidate to express with code this kind of situation. For this pattern, we need:
+
+  * Object literals to represent common constructions (house & building)
+  * A general function that can be used as a template
+
+Constructions expressed with object literals should have common methods like "foundations", "walls" or "roof" that symbolize key steps in every construction project. Then the template function can be used in the client code, passing it a construction as argument. This template function will create a house or a building by calling each method of the given construction in the right order.

GoF/idiomatic/Behavioral/Visitor/README.md

@@ -0,0 +1,20 @@
+# Synopsis
+
+I love history and I would like to visit more old monuments. But these are treasures of the past that must be protected to remain undamaged.
+
+# Problem
+
+If any individual can enter a historical monument and degrade it, we can say that the original structure is definitely lost. To preserve that structure, people should not be allowed to enter historical monuments without permission and supervision.
+
+Applied to JavaScript, we could say this is very easy to modify directly the structure of an object and we may be tempted to do so. *But this is not what we want...
+
+# Solution
+
+The Visitor design pattern is a way to preserve an object structure. Operations on this object structure are still possible but they are kept separate to some extent, so they do not modify its essence.
+
+To implement the Visitor design pattern, we can have:
+
+  * A factory function to create monuments
+  * An object literal to represent a tourist (visitor)
+
+Each monument has an "accept" method which takes a visitor object as parameter. The role of this method is to call the "visit" method of the visitor with a reference to the monument on which the "accept" method was called (using "this"). 

GoF/idiomatic/Creational/AbstractFactory/README.md

@@ -0,0 +1,14 @@
+# Synopsis
+
+I am a sysadmin and I work for a company where each employee can choose its operating system. So I often need to install and run various operating systems based on GNU/Linux, Mac OS or Windows.
+
+# Problem
+
+There are several families of operating systems and there are many operating systems in each family.
+If we try to handle all the instantiation logic in the client code, it will most likely be a mess.
+
+As a system administrator, you only want to know how to get an instance of a specific OS in a given family. You do not need to know how Debian, Mac OS X or Windows XP have been programmed to make them available on some computers.
+
+# Solution
+
+AbstractFactory is a great solution here. We could consider it as a superset of the Factory pattern, but there is significantly more work to do. Indeed, we need a factory function for each OS family and of course a factory of factories that will be the entry point of the associated module.

GoF/idiomatic/Creational/Builder/README.md

@@ -0,0 +1,19 @@
+# Synopsis
+
+I have to buy a new PC, but not a standardized one. On the manufacturer's website, I chose every single component before validating my order. Now I am looking forward to using this new computer!
+
+# Problem
+
+A PC contains a lot of components that are dynamically assembled by a third-party workforce which is employed by a manufacturer. Due to the flexibility of JavaScript, it would be possible to have only one object (the PC) and manipulate its properties directly. But this is not ideal if we want to keep the basic structure of the problem that comes from a real-life situation.
+
+# Solution
+
+The Builder pattern allows us to build our PC step by step with only three objects (literals):
+
+  * The PC
+  * The workforce (e.g. a geek)
+  * The manufacturer
+
+When the manufacturer will receive an order, it will ask its workforce to build the custom PC step by step through its "manufacture" method.
+
+N.B. Since we do not use constructor functions in the idiomatic style, this version of the Builder pattern is not a solution to the telescoping constructor problem. But you might be interested in the "Object Specifier" pattern...

GoF/idiomatic/Creational/Factory/README.md

@@ -0,0 +1,16 @@
+# Synopsis
+
+I am a fan of GNU/Linux distributions and I want to test the big names: Debian, RedHat, Slackware.
+
+# Problem
+
+Debian, RedHat and Slackware are all Linux distributions.
+We could create directly an object literal to represent each one, but this is not necessarily the best choice.
+We are not sure to use each instance in our code and we do not want to use memory for nothing.
+For the sake of clarity and performance, it may be nice to delegate the instantiation logic.
+
+# Solution
+
+Factory makes it possible to do so. To implement this design pattern, we only need to create a function that will return objects.
+
+In JavaScript, a function or method that returns objects is generally considered as a factory. It is a well-known idiomatic alternative to the use of the "new" keyword along with constructor functions.

GoF/idiomatic/Creational/Prototype/README.md

@@ -0,0 +1,24 @@
+# Synopsis
+
+When I order something, I sometimes like to have a paper invoice.
+But when the order is important, I do not want to lose the document.
+Therefore, I want to be able to make photocopies.
+
+# Problem
+
+Creating a new object with "new" is not the same thing as cloning an existing object.
+The good point about JavaScript is that the language is prototype-based.
+The built-in Object.create() method already performs some kind of cloning.
+However, we cannot clone properly if we only use Object.create().
+The parameter of this method (the original object) is used as the prototype of the new object.
+This means the new object will not have own properties like the original object.
+These properties would be available in the new object, but in its prototype.
+
+# Solution
+
+We need only two things in this situation:
+
+  * An object (literal) that we want to clone (e.g. invoice)
+  * A custom cloning function that will take the object to clone as a parameter
+
+N.B. Most of the time, it is not even useful to have an exact copy of an object in JavaScript. The important thing is often to be able to use the same properties on several objects, and for that purpose, a simple Object.create() is generally good enough.

GoF/idiomatic/Creational/Singleton/README.md

@@ -0,0 +1,19 @@
+# Synopsis
+
+As a person, I am unique. No one has exactly my DNA.
+
+# Problem
+
+In JavaScript, we can create several instances of everything using:
+
+  * An object literal: e.g. {}
+  * The static method "create" of "Object": e.g. Object.create(Object.prototype)
+  * The "new" operator on a constructor function: e.g. new Object()
+
+Therefore, I cannot be sure that there will not be other instances of myself in the code!
+
+# Solution
+
+Singleton is the key!
+
+But due to the nature of JavaScript, an object literal is already a sort of Singleton. Each object literal is unique and is built from the prototype of Object. In a way, we could see an object literal as a an anonymous class whose instance is delivered immediately. However, we could also argue that an object literal is nothing more than an instance of Object, which is actually true. With this in mind, it is quite obvious that an object literal is not a pure Singleton, but if flexibility matters, it is quite reasonable to consider it as a Singleton.

GoF/idiomatic/Structural/Adapter/README.md

@@ -0,0 +1,16 @@
+# Synopsis
+
+I have some amazing photos on my computer that I would like to display using my old projector. But my PC uses HDMI and my projector uses VGA.
+
+# Problem
+
+HDMI and VGA are not compatible interfaces. HDMI can handle images and sound through a digital signal whereas VGA can only handle images through an analog signal.
+
+# Solution
+
+Adapter is a well-known solution in this kind of situation. Here we need very few things:
+
+  * An object (literal) that represents the VGA connection
+  * An object (literal) that represents the HDMI to VGA adapter
+
+The latter must have a reference to the first one and must be the entry point of the module. Then the main method of the adapter will delegate some work to the main method of the VGA connection.