What is a Fluent API?

shoupn profile image Nick Shoup ・3 min read

This post was originally published on my blog Fundamentals of Code

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 {
    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
    this.start = start;
  //add value to our start value
     this.start += x;
     return this;

  //mulitply on our start value
    this.start = this.start * x;
    return this;
  //and of course we need to return our value
  //here we are using callbac function as well
    return this;


let returnResult = function(result){
//example of chaining the calculator functions
let cal = new Calculator(6)
    .equal(returnResult); //28


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.

Posted on Nov 8 '18 by:

shoupn profile

Nick Shoup


GIS Developer, outdoor enthusiast, cryptocurrency/blockchain enthusiast, father, and husband. I really just want to share my passion for coding with others.


markdown guide

With the help of Proxymise it even works with asynchronous functions.

There is also a proposal for a pipeline operator that will allow functional code to look more fluent without the need of this. g(f(x)) becomes x |> f |> g


That's awesome. I'll check out Proxymise. Looks like a neat wrapper for handling async code. As you said help's to remove a lot of the .then()'s


There is but one thing I HATE about fluent api - the code looks quite ugly. The indentation is screwed up if you chain more calls and it looks ridiculous if you have to nest a few levels... and it's quite easy to fall into that as well.

PS: Your equals should return the value instead of calling a callback. The code looks much more sane this way.


I agree about fluent api's becoming quickly hard to read and if you start nesting, then try something different.

BTW, the equals accepts either a call back or returns the result. I should check if there was a callback passed to it, though as a param.


Equal returns "this", not the result. The only other note I have about the example is that the internal property is called "start" instead of "result" (because this is what it is - it's the result, start is only the initial value).

Here is some food for thought:


Chaining has no performance benefit over calling the methods separately. Calling a callback to return the result however has a very dramatic performance impact.