What is a Fluent API?

Fluent API and Chaining

If you come from a .NET background, you’ve probably been exposed to Linq, or if you’ve developed in JavaScript, you’ve probably used jQuery. Both of these examples have a type of syntax are what is commonly referred to as a fluent API. Another term commonly used to describe the syntax is chaining. A jQuery example looks like the following bit of code:

$( "div" ).css( "border", "9px solid black" ).html("Hello Chained API!");

Notice that we call the initial selector function on our div elements, then we immediately call the css function, followed by the html function. This is what a chained or fluent API is. This is a very common pattern in JavaScript and I’m going to demonstrate to you how to create your own. This is a handy pattern to know.

this keyword

The key to creating your own fluent API, is to use the instance object of your JavaScript class. To do this you need to understand a little bit about the this keyword. Basically this refers to the instance of our object that is created. Whenever you use the new keyword you are using the constructor function that is on all Object.prototype‘s. After using the new keyword you have an instance of this in the object. this was created when you called the constructor function by using the new keyword. Previous to ES6 you had to be concerned with closure and would often reassign this to another variable like so: var self = this;, but from what I have found is that this using the conventions of ES6, most of the issues with global scope creep of variables is done away with if you use the let and const variable keywords and stay away from using var. Also using fat arrow functions affects closure in much the same way, but that’s a topic for another post.

Calculator API

Here we are going to create the beginning of our calculator class. notice the constructor function and our this keyword.

class Calculator {
  constructor(start){
    this.start = start;
  }
}

If we were to instantiate a new instance of our calculator class it would go like this:

let cal = new Calculator(5);

At this point, our Calculator class isn’t doing much :\ So let’s add a couple of additional functions using our best ES6 class syntax. Let’s also throw in a returnValue() callback function and get something working. Check out the below codepen and add a subtraction and division function to this class. See how to chain multiple together, as well as throw in some error handling and checking for value types. I’d be excited to see what you come up with.

Example of Course

You can view the same on codepen here.

class Calculator {
 //start value passed into constructor
  constructor(start){
    this.start = start;
  }
  //add value to our start value
  add(x){
     this.start += x;
     return this;
  }
 
  //mulitply on our start value
  multiply(x){
    this.start = this.start * x;
    return this;
  }
  //and of course we need to return our value
  //here we are using callbac function as well
  equal(callback){
    callback(this.start);
    return this;
  }
 
}
 
let returnResult = function(result){
  console.log(result);
}
//example of chaining the calculator functions
let cal = new Calculator(6)
    .add(1)
    .multiply(4)
    .equal(returnResult); //28

Chained

This whole implementation of creating a functioning fluent API requires passing the same object from one function call to the next. Instead of creating a Calculator you could create something like a document and querySelector API with the ability to do some ajax calls, and maybe someday come up with something like a jQuery replacement? Dunno, but it’d be fun to do.