Posts on t3h2mas.xyz

Fluent Builder with JavaScript

Tue, 09 Jun 2020 00:00:00 +0000

Photo by Scott Blake on Unsplash

Experimenting with implementing the fluent builder pattern in JavaScript.

The fluent builder pattern is a composition of the builder pattern and the fluent interface pattern.

It’s a pattern that holds our hand through the maze of object construction.

Our implementation uses es6 classes to give us something resembling a fluent builder.

Traditionally fluent interfaces are built using… interfaces.

Vanilla JavaScript doesn’t have interfaces. We’re left to do what we can with what we have.

(This is where someone says something about TypeScript. Have at it, but I never said I was writing about TypeScript. However, I would be delighted to see someone implement their own Fluent Builder in TypeScript or your language of choice)

For the curious, here is my attempt at implementing the pattern using JSDOC interfaces. I changed approaches after I realize that editor behavior was different between implementations.

How to build a burrito

To get to where we’re going first we will have to take a look at the builder pattern.

Wikipedia summarizes the pattern as

The builder pattern is a design pattern designed to provide a flexible solution to various object creation problems in object-oriented programming.

The intent of the Builder design pattern is to separate the construction of a complex object from its representation. It is one of the Gang of Four design patterns.

That’s right. We are about to attempt to apply an object-oriented design pattern from a book[1] written in 1984 to JavaScript in 2020. What a time to be alive!

Anyway…

Maybe we want to make a burrito… Relax, this isn’t a monad tutorial

/**
 * Everyone loves Burritos
 */
class Burrito {
/**
 * @param {string} protein
 * @param {string} carb
 * @param {?string} salsa
 * @param {?string} cheese
 */
constructor(protein, carb, salsa, cheese) {
// required toppings
 this.protein = protein;
this.carb = carb;
// optional toppings
 this.salsa = salsa;
this.cheese = cheese;
}
}

Our take on a burrito has the following properties required in the constructor

a carb(ohydrate) such as brown or white rice
a protein such as shredded pork or beef

The following are optional (for whatever reason)

a salsa of some variety
cheese, queso, that ripe, runny, young or old fromage

Making (or constructing) a burrito as shown could look like this

const burrito = new Burrito(
"brown rice",
"shredded pork",
"green salsa",
"cojita"
);
// do stuff to the burrito

If this burrito gets popular somehow we’re going to have to continue to make more and more burritos. Passing parameter after parameter in the same order to our Burrito.constructor [2]

We pass the parameters at the same time to construct the class instance.

To be annoyingly repetitive, using individual parameters got the job done, but have implications such as

all parameters must be passed at the same time
each parameter must be passed in the correct order
the constructor definition grows with each new parameter passed [3]

Now we will attempt to bypass these implications using a builder… (The burrito in the following snippet is the same one we looked at before.)

/**
 * Everyone loves Burritos
 */
class Burrito {
/**
 * @param {string} protein
 * @param {string} carb
 * @param {?string} salsa
 * @param {?string} cheese
 */
constructor(protein, carb, salsa, cheese) {
// required toppings
 this.protein = protein;
this.carb = carb;
// optional toppings
 this.salsa = salsa;
this.cheese = cheese;
}
}
/*
 * BurritoBuilder adds flexibility to burrito construction
 */
class BurritoBuilder {
constructor() {
this.toppings = {}; // 1
 }
// 2
 /**
 * Add a protein to burrito
 * @param {string} protein
 * @returns {BurritoBuilder}
 */
withProtein(protein) {
this.toppings.protein = protein;
return this; // 3
 }
/**
 * Add a carbohydrate to burrito
 * @param {string} carb
 * @returns {BurritoBuilder}
 */
withCarb(carb) {
this.toppings.carb = carb;
return this;
}
/**
 * Add salsa to our burrito
 * @param {salsa} salsa
 * @returns {BurritoBuilder}
 */
withSalsa(salsa) {
this.toppings.salsa = salsa;
return this;
}
/**
 * Add cheese to our burrito
 * @param {string} cheese
 * @returns {BurritoBuilder}
 */
withCheese(cheese) {
this.toppings.cheese = cheese;
return this;
}
// 4
 /**
 * Wrap our toppings into a finished burrito
 * @returns {Burrito}
 */
build() {
const { protein, carb, cheese, salsa } = this.toppings;
return new Burrito(protein, carb, cheese, salsa);
}
}

There is a lot to unpack from our builder implementation! Let’s break down a few key points

We store toppings in an object as a class property
Topping adding methods follow the pattern of .with[ToppingName]
We return a reference to the instance of the Burrito Builder after adding each ingredient
Finally, we have a build method that will attempt to build a burrito using the toppings we selected. This method ties the room together by providing a tortilla wrapped resolution

Enough with the lists, time to put our BurritoBuilder to use!

const burrito = new BurritoBuilder()
.withCarb("brown rice")
.withSalsa("green")
.withCheese("cojita")
.withProtein("shredded pork")
.build();

In this example we’re passing all the ingredients at once. We’re able to build a burrito in one statement by method chaining. Method chaining is one flavor found in builders and is available because we return a reference to the builder in every method besides the finalizing build. (The return this in each chain-able method allows us to chain, but we are still free to assign our burrito-to-be to a variable whenever we’d like.)

We could easily do something in the spirit of 2020 era popular “healthy fast food” burrito joints

class CarbStation {
static addIngredient(burrito, ingredient) {
return burrito.withCarb(ingredient);
}
}
class GrillStation {
static addIngredient(burrito, ingredient) {
return burrito.withProtein(ingredient);
}
}
class ExtraStation {
static addIngredient(burrito, category, ingredient) {
if (category === "salsa") {
return burrito.withSalsa(ingredient);
}
if (category === "cheese") {
return burrito.withCheese(ingredient);
}
throw new Error("We don't sell that here!");
}
}
class Cashier {
// oops, no register logic, free burritos
 static pay(burrito) {
return burrito.build();
}
}

Let’s recreate our burrito from before. Notice how we’re passing a burrito builder around from class to class so they can each add toppings with love and care. Construction of the burrito is delayed until we see fit.

// Warning, the following may offend you if you only speak const or point-free
const burritoBuilder = new BurritoBuilder(); // (reference #1)

let burritoWithCarb = CarbStation.addIngredient(burritoBuilder, "brown rice"); // (reference #2)
let burritoWithCarbAndProtein = GrillStation.addIngredient(
burritoWithCarb,
"shredded pork"
); // (reference #3)

ExtraStation.addIngredient(burritoWithCarbAndProtein, "guac", true);
ExtraStation.addIngredient(burritoWithCarbAndProtein, "salsa", "green salsa");
ExtraStation.addIngredient(burritoWithCarbAndProtein, "cheese", "cojita");
const readyToEatBurrito = Cashier.pay(burritoWithCarbAndProtein);

Notice a few things here.

We can reference our burrito mid-construction with chaining or by variable assignment
We have 3 different variables (marked with comments) referencing the same thing
BurritoBuilder#build must be called when we’re ready to finalize our burrito build out
We passed around an incomplete burrito builder. We called methods that independently added their own modifications.

So far we have briefly explored the second component of the term “fluent builder.” In true LIFO fashion, we will now look at the “fluent” component.

Fluent interfaces

Martin Fowler suggests that the term “fluent interface” is synonymous with an internal domain specific language.

In a summary of Fowler’s post, Piers Cawley poetically describes the fluent interface as a way to “move [sic moving] object construction behind a thoughtful, humane interface."

Our implementation will be using classes to work around JavaScripts lack of interfaces.

Without further ado, let’s introduce a plot twist so we can try to construct burritos behind a thoughtful, humane “interface.”

A wild boss appears

You’re sitting at your keyboard when suddenly a wild boss appears Boss > Your burrito code has been working for us so far but there’s a problem! When I presented the code to the client (Healthy Burrito Chain) they told us about some business rules we failed to discover in the original project specification! You > Oh no! Not surprise business rules! Boss > Instead of filing TPS reports on Saturday, you need to come in and make sure we enforce the following rules when creating burritos…

(The rules the boss give you are as follows)

In order for a burrito to be built, it must have a carb and a protein. We cannot allow a burrito to be created without these ingredients.
After the required ingredients are submitted, we must allow customers to either pay or add one or more extra ingredient.
The extra ingredients are salsa, and cheese

Oh No you think. It’s going to be a long weekend….

Saturday rolls around

Instead of throwing out the decision to use the builder pattern for our burritos, maybe we can make some adjustments by making our builder fluent.

Another way to look at our new business model by translating our burrito shop into a finite state machine

fluent builder finite state machine

Shut up and show me the code

Let us take our implementation, wrap it with some classes. Hopefully whatever comes out won’t make Mr. Fowler cringe.

We’ll start with a class that allows us to set the protein.

class ProteinSetter {
/**
 * @param {BurritoBuilder} builder
 */
constructor(builder) {
// 1
 this.builder = builder;
}
/**
 * @param {string} protein
 * @returns {CarbSetter}
 */
withProtein(protein) {
// 2
 return new CarbSetter(this.builder.withProtein(protein));
}
}

Notes:

Our ProteinSetter class takes our builder from before. We’re wrapping the existing builder class instead of replacing the implementation.
We pass the builder to the CarbSetter class after choosing a protein.

The CarbSetter class looks like this

class CarbSetter {
/**
 * @param {BurritoBuilder} builder
 */
constructor(builder) {
this.builder = builder;
}
/**
 * @param {string} carb
 * @returns {ExtraSetter}
 */
withCarb(carb) {
return new ExtraSetter(this.builder.withCarb(carb));
}
}

This class is pretty similar to the ProteinSetter we just saw. After the carb is set, we pass our builder along to the ExtraSetter.

Are you starting to see the pattern here? We return class instances to control the flow of burrito construction.

The ExtraSetter class looks like this

class ExtraSetter {
/**
 * @param {BurritoBuilder} builder
 */
constructor(builder) {
this.builder = builder;
}
/**
 * @param {number} salsa
 * @returns {ExtraSetter}
 */
withSalsa(salsa) {
this.builder.withSalsa(salsa);
return this;
}
/**
 * @param {string} cheese
 * @returns {ExtraSetter}
 */
withCheese(cheese) {
this.builder.withCheese(cheese);
return this;
}
/**
 * @returns {Burrito}
 */
wrapUp() {
return this.builder.build();
}
}

Just like the other classes that we’ve seen, except for one crucial detail. The ExtraSetter can complete a build.

Our extra setter can:

Add optional toppings in any order
Complete the construction of our tortilla wrapped master piece

This last class is our entry point to the fluent burrito builder work flow.

/**
 * FluentBuilder to use as a starting point
 */
class FluentBuilder {
static onTortilla() {
return new ProteinSetter(new BurritoBuilder());
}
}

Drum roll, please

Now for the moment we’ve all been waiting for…

We can use our Fluent Builder as follows

const burrito = FluentBuilder.onTortilla()
.withProtein("a")
.withCarb("brown rice")
.withCheese("cojita")
.wrapUp();

This is valid usage. Most editors will guide us down this path. Unlike the BurritoBuilder we can only call the methods that were intentionally exposed at any particular stage.

Fluent Builder in action

We’re forced down the happy path.

Go ahead, try it. Try to create a burrito using the FluentBuilder methods without adding a protein. That’s right, you can’t without directly accessing the builder (which is totally cheating)

I love it, how can I use it?

Personally I’ve been using Fluent Builders to constrain the construction of DTOs in tests and the application layer.

Feedback

Yes please @teh2mas

[1] https://en.wikipedia.org/wiki/Design_Patterns

[2] A common pattern JavaScript is to pass multiple parameters into a class constructor, method, or function as an object like

class Burrito({ carb, protein, salsa, cheese }) { /* ... */ }

Which is a fine way of taking advantage of destructuring. We are also free to pass the parameters in whichever order we’d like.

[3] This can be a code smell hinting at a chance to decompose our class into smaller components

Hello World! The Pythonic way

Wed, 06 Apr 2016 04:05:25 -0600

IRC bot in python

Hello world

The first program developers are often introduced to is the infamous Hello World. It doesn’t matter what language you’re using, you have probably seen one. If not in a tutorial, than out in the wild.

The why

This post is to celebrate Free Code Camp expanding towards supporting Python, among other cool languages. Check out the announcement for yourself.

Note that this post isn’t meant to be a tutorial for brand new programmers. I have included links to help readers get started with Python.

Show me some code

Enough talk. Let’s check out the way you would write Hello World in Python. Deep breath now. And off we go.

Python3

print('Hello World!')

Fascinating right? Those of you who are used to JavaScript might not be very impressed. The JS Hello World example wouldn’t be much different.

JavaScript

console.log("Hello World!");

Ruby

Ruby’s is in the same ballpark

puts "Hello World!"

To put the simplicity of these into context let’s look at another two examples.

C

#include <stdio.h>

int main(int argc, char* argv[])
{
printf("Hello World!\n");
return 0;
}

Java

public class HelloWorld {
public static void main(String[] args) {
System.out.prinln("Hello World!");
}
}

There has been a shift in the last few years where the programming community has started to lean towards the prior three languages as introductory languages over the latter two. Perhaps these Hello World’s give you a small taste of why. What do you think?

Okay, back to Python.

What about this Pythonic thing?

I will use this last section to skim the surface of what the word Pythonic is and we will look at a Pythonic Hello World.

What the hell is Pythonic?

When people think about this question, they may think of Python’s famous

import this

example. Which when ran will give you this:

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Take from that what you will. Let’s focus on one line from the text.

There should be one– and preferably only one –obvious way to do it.

To me this line describes the mentality behind the word Pythonic and idiomatic Python.

If you’re falling asleep at the keyboard, at least add this to your reading list.

Shouldn’t there always be ‘one way to do it?’

That’s up to you. Despite what language you use. Let’s look at an example from the Perl community (which Ruby has inherited.)

There’s more than one way to do it (TMTOWTDI or TIMTOWTDI, pronounced Tim Toady) There’s more than one way to do it - Wikipedia, the free encyclopedia > *There’s more than one way to do it ( TMTOWTDI or TIMTOWTDI, pronounced Tim Toady) is a Perl programming motto. The…*en.wikipedia.org

(TIL there’s a pronunciation!)

Back to the code

Let’s skip the rest of the philosophy lesson and dive into the Pythonic Hello World code example. I’m going to include a very basic function (oh my!) so it’s not so confusing when we look at the lines.

is how you start a Python comment

# section one
def main():
print("Hello World!")
# section two
if __name__ == "__main__":
main()

Okay?

Tear it down

Section one

def main():
print("Hello World!")

define a function that takes no arguments and doesn’t return any value named main

print Hello World! to the console when main is called

Section two

if __name__ == "__main__":
main()

name is assigned to the calling module…

In short:

if the module is imported name will be the set to the importing module
if the file is directly ran then execute the if statement

Let’s look at one more modified example before we wrap this up

# fcc-greet.py
def greet(name):
print("Hello {}, welcome to Free Code Camp!".format(name))
if __name__ == "__main__":
from sys import argv
greet(argv[1]) # first command argument

The print statement and the last line may be a little much for some newer users. Instead of explaining them I’m going to show you two different ways to use our new Python program.

The first is through the terminal/command prompt:

$ python fcc-greet.py t3h2mas

which prints this to the console

Hello t3h2mas, welcome to Free Code Camp!

Using fcc-greet.py as a module:

# my-program.py
import fcc-greet
users = ["t3h2mas", "BoilingOil", "mamptecnocrata"]
map(fcc-greet.greet, users)

thank you to the above users for their permission to use their username :+1:

which would output

Hello t3h2mas, welcome to Free Code Camp! Hello BoilingOil, welcome to Free Code Camp! Hello mamptecnocrata, welcome to Free Code Camp!

That last example might have a little much going on. Just focus on the output!

That completes our example program using Pythonic idioms. We finished with a program that can be called from the prompt with a supplied argument as well being used as a module easily from different programs.

wrap up

This concludes our small taste of idiomatic Python. This post was intended to be supplementary reading rather than a full scope tutorial. The Python community sure knows what it likes. See

pep8 Python style guide Welcome to Python.org *This document gives coding conventions for the Python code comprising the standard library in the main Python…*www.python.org

pep257 Welcome to Python.org *The aim of this PEP is to standardize the high-level structure of docstrings: what they should contain, and how to say…*www.python.org

for more on Pythonic guides.

new to Python?

This looks like a good starting point Getting started with python - The Python Guru *Python is a general purpose programming language created by Guido Van Rossum. Python is most praised for its elegant…*thepythonguru.com

Here’s a great list of tutorials…

For programmers: BeginnersGuide/Programmers - Python Wiki *Because this is a Wiki page, users can edit it. You are therefore free to add details of material that other Python…*wiki.python.org

For beginners BeginnersGuide/NonProgrammers - Python Wiki *If you’ve never programmed before, the tutorials on this page are recommended for you; they don’t assume that you have…*wiki.python.org

Python Communities

Reddit: Python Education * /r/learnpython *Subreddit for posting content, questions, and asking for general advice about learning the Python programming language.*reddit.com Python * /r/Python news about the dynamic, interpreted, interactive, object-oriented, extensible programming language Pythonreddit.com learn programming * /r/learnprogramming *A subreddit for all questions related to programming in any language.*reddit.com

Gitter: FreeCodeCamp/FreeCodeCamp *Welcome to our main chat room. We have many official chat rooms for hanging out and getting help. Here’s the list…*gitter.im FreeCodeCamp/python *This is the best place to discuss Python and get help with it. Be sure to check out https://github.com/freecodecamp…*gitter.im

IRC: Python.org -IRCGuide The official home of the Python Programming Languagewww.python.org

Applying JavaScript: User Scripts

Fri, 01 Apr 2016 04:05:25 -0600

Art credit

Writing a Userscript is a fun way to use your JavaScript skills. It takes you out of the editor into the browser with real time feedback and validation.

What is a user script?

Userscripts (a.k.a User Scripts, User scripts, or .user.js) are open-source licensed add-ons for web browsers that change web pages as they are loaded. They give users the power to make websites do what they want them to, rather than what was originally intended.

User scripts are written in JavaScript and allow you to tweak the look and feel of a webpage on your browser. The scripts only effect your browser, not the actual webpage.

A quick warning

You should be aware of privacy issues when using userscripts, and should not install them from sources you do not trust. Userscripts can carry out actions on your behalf and can potentially access any information on a website you have access to, or that you enter into a website. They are often permitted to carry out functions that scripts on normal websites cannot, such as storing information on your computer and sharing it between website. Badly written userscripts could potentially also be exploited by malicious websites.

explanations taken from https://github.com/OpenUserJs/OpenUserJS.org/wiki/Userscript-Beginners-HOWTO

Why user scripts?

Free Code Camp has a lot of great real world projects that will enrich your skill set and portfolio. I personally like using the skills I have learned in JavaScript, jQuery, and CSS to modify my day to day browsing.

Some User Scripts have been extremely popular and were made into browser extensions. An example of one would be the Reddit Enhancement Suite found at http://redditenhancementsuite.com/.

You too could use your user script as a base of a browser extension!

Getting started

User scripts are run from browser extensions themselves. Grease Monkey (FireFox) was the pioneer add on to allow people to customize their browsing experience. Install the appropriate plug in for your browser.

For FireFox: Grease Monkey Greasemonkey *The Development Channel lets you test an experimental new version of this add-on before it’s released to the general…*addons.mozilla.org

For Chrome: Tamper Monkey Tampermonkey The most popular userscript manager for Blink-based browserschrome.google.com

For this tutorial I will be using Chrome with Tamper Monkey.

There shouldn’t be any significant differences with the process after installing either Grease Monkey or Tamper Monkey.

Just in case, here is a quick link to installing Grease Monkey (as well as making a few things with it.) Greasemonkey Tutorial for Beginners *In Greasemonkey tutorial, I have covered how to write Greasemonkey user scripts. After this tutorial,you will be able…*hayageek.com

the project

We are going to be making a slight change to the home page on Hacker News http://news.ycombinator.com.

HackerNews homepage

We will be using jQuery to make alternating links background colors slightly different to improve readability.

start a new script

Click on the Tamper Monkey icon in the top right and select ‘Add a new script’ from the dialog box.

You should be brought to a new tab that looks like this

new script page

Fill in the information

After starting a new script the first thing we want to do is fill in the script information at the top. Go ahead and fill in the following attributes how ever you want

name
description
author

I will show you what mine looks like as well.

Add jQuery

right before the line

// ==/UserScript==

add a line with the text of

// @require http://code.jquery.com/jquery-latest.js

Think of this as importing/requiring jQuery for a JS project.

here is mine

script info filled out

Hello script.js!

Let’s see if it our script loads on http://news.ycombinator.com and jQuery is good to go.

After the // *your code here *line add the following code

$(document).ready(function () {
alert("WINNING");
});

and enter **Ctrl + s **or click on the save button on the left

You may be brought to the following page. If not, click on the Installed userscripts tab.

installed userscripts page

Awesome! Out script is loaded into Tamper Monkey. The green dot on the left means that the script is turned on. You can even see the Hacker News logo in the screenshot.

execute the script

Visit Hacker News in your browser and if you’ve been following along and everything went well, you should see

working alert dialog

Fire up the debugger

It’s time to find the post elements we want to modify. Enter Ctrl + Shift + i to bring up the browser debugger.

Now we want to select an element to take a closer look. Clicking on the blue square with the mouse in it at the top left of the debugger will open the element selector. You can also use the key command Ctrl + Shift + c.

element selector

As you can see I found an element called td.title. After clicking on it the element is highlighted in the elements tab of the debugger (also shown above.)

Highlighting the element above our title called

<tr class="athing">

selects this in the browser

BINGO

Bingo. It looks like we found the element we want. Hacker News has a clean HTML layout so it wasn’t too difficult to find our target element.

If you remember your jQuery, all you have to do to find all of the post elements is use the selector

$(".athing");

do something to our post element

Now that we have a way to select our element with jQuery we can alter our element. Let’s change the background color of the posts using the following code. Change the $(document).ready() code to this

$(document).ready(function () {
$(".athing").css("background-color", "#DDD");
});

note: #DDD is shorthand for #DDDDDD

let’s look at the resulting page. Remember to save your userscript then refresh the HackerNews page. You may have to close your debugger to view the whole page.

altered Hacker News front page

Are we done yet? Not quite. We have changed all of our post elements instead of alternating. It may look like the zebra effect we wanted but that’s only because the score/subinfo element isn’t effected._ If you feel inclined to alter that element as well please do and feel free to post your method in the comments. It’s outside of the scope of this guide._

Oh no?! What do we do… I don’t want to write any loops!

jQuery to the rescue

Have no fear, fellow Campers. jQuery has come to the rescue yet again.

jQuery provides special selectors just for an occasion like this.

Now introducing :odd** :odd Selector** *Description: Selects odd elements, zero-indexed. See also even. In particular, note that the 0-based indexing means…*api.jquery.com

all we have to do is add :odd to the end of our selector so that the line looks like this. note: I have also changed the color to #EEE; to blend in better.

$(".athing:odd").css("background-color", "#EEE");

Save your script and refresh HackerNews and you should see this final product

final product

Wrapping up

There you have it. Now you have another creative outlet to unleash your budding coding wizardry on! User Scripts can be used to tweak the functionality or look of a site, to add a feature you’ve always wanted, plus much more.

Homework

Write your own User Script to add something to a website you use often. Whether it be styling or a button that can toggle the visibility of certain elements, it’s all up to you. Provide your product in the comments here!

Go forth and conquer Campers!