DEV Community: Bill Sourour

Elegant patterns in modern JavaScript: Ice Factory

Bill Sourour — Sun, 06 May 2018 02:03:32 +0000

I’ve been working with JavaScript on and off since the late nineties. I didn’t really like it at first, but after the introduction of ES2015 (aka ES6), I began to appreciate JavaScript as an outstanding, dynamic programming language with enormous, expressive power.

Over time, I’ve adopted several coding patterns that have lead to cleaner, more testable, more expressive code. Now, I am sharing these patterns with you.

I wrote about the first pattern — “RORO” — here. Don’t worry if you haven’t read it, you can read these in any order.

Today, I’d like to introduce you to the “Ice Factory” pattern.

An Ice Factory is just a function that creates and returns a frozen object. We’ll unpack that statement in a moment, but first let’s explore why this pattern is so powerful.

JavaScript classes are not so classy

It often makes sense to group related functions into a single object. For example, in an e-commerce app, we might have a cart object that exposes an addProduct function and a removeProduct function. We could then invoke these functions with cart.addProduct() and cart.removeProduct().

If you come from a Class-centric, object oriented, programming language like Java or C#, this probably feels quite natural.

If you’re new to programming — now that you’ve seen a statement like cart.addProduct(). I suspect the idea of grouping together functions under a single object is looking pretty good.

So how would we create this nice little cart object? Your first instinct with modern JavaScript might be to use a class. Something like:

// ShoppingCart.js

export default class ShoppingCart {
  constructor({db}) {
    this.db = db
  }

  addProduct (product) {
    this.db.push(product)
  }

  empty () {
    this.db = []
  }

get products () {
    return Object
      .freeze([...this.db])
  }

removeProduct (id) {
    // remove a product 
  }

// other methods

}

// someOtherModule.js

const db = [] 
const cart = new ShoppingCart({db})
cart.addProduct({ 
  name: 'foo', 
  price: 9.99
})

Note : I’m using an Array for the db parameter for simplicity’s sake. In real code this would be something like a Model or Repo that interacts with an actual database.

Unfortunately — even though this looks nice — classes in JavaScript behave quite differently from what you might expect.

JavaScript Classes will bite you if you’re not careful.

For example, objects created using the new keyword are mutable. So, you can actually re-assign a method:

const db = []
const cart = new ShoppingCart({db})

cart.addProduct = () => 'nope!' 
// No Error on the line above!

cart.addProduct({ 
  name: 'foo', 
  price: 9.99
}) // output: "nope!" FTW?

Even worse, objects created using the new keyword inherit the prototype of the class that was used to create them. So, changes to a class’ prototype affect all objects created from that class — even if a change is made after the object was created!

Look at this:

const cart = new ShoppingCart({db: []})
const other = new ShoppingCart({db: []})

ShoppingCart.prototype.addProduct = () => ‘nope!’
// No Error on the line above!

cart.addProduct({ 
  name: 'foo', 
  price: 9.99
}) // output: "nope!"

other.addProduct({ 
  name: 'bar', 
  price: 8.88
}) // output: "nope!"

Then there's the fact that this In JavaScript is dynamically bound. So, if we pass around the methods of our cart object, we can lose the reference to this. That’s very counter-intuitive and it can get us into a lot of trouble.

A common trap is assigning an instance method to an event handler.

Consider our cart.empty method.

empty () {
    this.db = []
  }

If we assign this method directly to the click event of a button on our web page…

<button id="empty">
  Empty cart
</button>

---

document
  .querySelector('#empty')
  .addEventListener(
    'click', 
    cart.empty
  )

… when users click the empty button, their cart will remain full.

It fails silently because this will now refer to the button instead of the cart. So, our cart.empty method ends up assigning a new property to our button called db and setting that property to [] instead of affecting the cart object’s db.

This is the kind of bug that will drive you crazy because there is no error in the console and your common sense will tell you that it should work, but it doesn’t.

To make it work we have to do:

document
  .querySelector("#empty")
  .addEventListener(
    "click", 
    () => cart.empty()
  )

Or:

document
  .querySelector("#empty")
  .addEventListener(
    "click", 
    cart.empty.bind(cart)
  )

I think Mattias Petter Johansson said it best:

“new and this [in JavaScript] are some kind of unintuitive, weird, cloud rainbow trap.”

Ice Factory to the rescue

As I said earlier, an Ice Factory is just a function that creates and returns a frozen object. With an Ice Factory our shopping cart example looks like this:

// makeShoppingCart.js

export default function makeShoppingCart({
  db
}) {
  return Object.freeze({
    addProduct,
    empty,
    getProducts,
    removeProduct,
    // others
  })

function addProduct (product) {
    db.push(product)
  }

  function empty () {
    db = []
  }

function getProducts () {
    return Object
      .freeze(db)
  }

function removeProduct (id) {
    // remove a product
  }

// other functions
}

// someOtherModule.js

const db = []
const cart = makeShoppingCart({ db })
cart.addProduct({ 
  name: 'foo', 
  price: 9.99
})

Notice our “weird, cloud rainbow traps” are gone:

We no longer need new . We just invoke a plain old JavaScript function to create our cart object.
We no longer need this . We can access the db object directly from our member functions.
Our cart object is completely immutable. Object.freeze() freezes the cart object so that new properties can’t be added to it, existing properties can’t be removed or changed, and the prototype can’t be changed either. Just remember that Object.freeze() is shallow , so if the object we return contains an array or another object we must make sure to Object.freeze() them as well. Also, if you’re using a frozen object outside of an ES Module, you need to be in strict mode to make sure that re-assignments cause an error rather than just failing silently.

A little privacy please

Another advantage of Ice Factories is that they can have private members. For example:

function makeThing(spec) {
  const secret = 'shhh!'

return Object.freeze({
    doStuff
  })

function doStuff () {
    // We can use both spec
    // and secret in here 
  }
}

// secret is not accessible out here

const thing = makeThing()
thing.secret // undefined

This is made possible because of Closures in JavaScript, which you can read more about on MDN.

A little acknowledgement please

Although Factory Functions have been around JavaScript forever, the Ice Factory pattern was heavily inspired by some code that Douglas Crockford showed in this video.

Here’s Crockford demonstrating object creation with a function he calls “constructor”:

Douglas Crockford demonstrating the code that inspired me.

My Ice Factory version of the Crockford example above would look like this:

function makeSomething({ member }) {
  const { other } = makeSomethingElse() 

  return Object.freeze({ 
    other,
    method
  })

function method () {
    // code that uses "member"
  }
}

I took advantage of function hoisting to put my return statement near the top, so that readers would have a nice little summary of what’s going on before diving into the details.

I also used destructuring on the spec parameter. And I renamed the pattern to “Ice Factory” so that it’s more memorable and less easily confused with the constructor function from a JavaScript class. But it’s basically the same thing.

So, credit where credit is due, thank you Mr. Crockford.

Note: It’s probably worth mentioning that Crockford considers function “hoisting” a “bad part” of JavaScript and would likely consider my version heresy. I discussed my feelings on this in a previous article and more specifically, this comment.

What about inheritance?

If we tick along building out our little e-commerce app, we might soon realize that the concept of adding and removing products keeps cropping up again and again all over the place.

Along with our Shopping Cart, we probably have a Catalog object and an Order object. And all of these probably expose some version of addProduct and removeProduct.

We know that duplication is bad, so we’ll eventually be tempted to create something like a Product List object that our cart, catalog, and order can all inherit from.

But rather than extending our objects by inheriting a Product List, we can instead adopt the timeless principle offered in one of the most influential programming books ever written:

“Favor object composition over class inheritance.”

– Design Patterns: Elements of Reusable Object-Oriented Software.

In fact, the authors of that book — colloquially known as “The Gang of Four” — go on to say:

“…our experience is that designers overuse inheritance as a reuse technique, and designs are often made more reusable (and simpler) by depending more on object composition.”

So, here’s our product list:

function makeProductList({ productDb }) {
  return Object.freeze({
    addProduct,
    empty,
    getProducts,
    removeProduct,
    // others
  )}
  // definitions for 
  // addProduct, etc...
}

And here’s our shopping cart:

function makeShoppingCart(productList) {

return Object.freeze({
      items: productList,
      someCartSpecificMethod,
      // ...
    )}

function someCartSpecificMethod () {
    // code 
  }
}

And now we can just inject our Product List into our Shopping Cart, like this:

const productDb = []
const productList = makeProductList({ productDb })

const cart = makeShoppingCart(productList)

And use the Product List via the items property. Like:

cart.items.addProduct()

It may be tempting to subsume the entire Product List by incorporating its methods directly into the shopping cart object, like so:

function makeShoppingCart({ 
   addProduct,
   empty,
   getProducts,
   removeProduct,
   ...others
  }) {

return Object.freeze({
      addProduct,
      empty,
      getProducts,
      removeProduct,
      someOtherMethod,
      ...others
    )}

function someOtherMethod () {
    // code 
  }
}

In fact, in an earlier version of this article, I did just that. But then it was pointed out to me that this is a bit dangerous (as explained here). So, we're better off sticking with proper object composition.

Awesome. I’m Sold!

Careful

Whenever we’re learning something new, especially something as complex as software architecture and design, we tend to want hard and fast rules. We want to hear thing like “always do this” and “ never do that.”

The longer I spend working with this stuff, the more I realize that there’s no such thing as always and never. It’s about choices and trade-offs.

Making objects with an Ice Factory is slower and takes up more memory than using a class.

In the types of use case I’ve described, this won’t matter. Even though they are slower than classes, Ice Factories are still quite fast.

If you find yourself needing to create hundreds of thousands of objects in one shot, or if you’re in a situation where memory and processing power is at an extreme premium you might need a class instead.

Just remember, profile your app first and don’t prematurely optimize. Most of the time, object creation is not going to be the bottleneck.

Despite my earlier rant, Classes are not always terrible. You shouldn’t throw out a framework or library just because it uses classes. In fact, Dan Abramov wrote pretty eloquently about this in his article, How to use Classes and Sleep at Night.

Finally, I need to acknowledge that I’ve made a bunch of opinionated style choices in the code samples I’ve presented to you:

I use function statements instead of function expressions.
I put my return statement near the top (this is made possible by my use of function statements, see above).
I name my factory function, makeX instead of createX or buildX or something else.
My factory function takes a single, destructured, parameter object.
I don’t use semi-colons (Crockford would also NOT approve of that)
and so on…

You may make different style choices, and that’s okay! The style is not the pattern.

The Ice Factory pattern is just: use a function to create and return a frozen object. Exactly how you write that function is up to you.

If you’ve found this article useful help me spread the word with some hearts and unicorns! And if you'd like to learn more stuff like this, please sign up for my Dev Mastery newsletter below. Thanks!

Dev Mastery Newsletter Sign Up

I keep your info private and I never SPAM.

Elegant patterns in modern JavaScript: RORO

Bill Sourour — Tue, 20 Mar 2018 19:51:51 +0000

I wrote my first few lines of JavaScript not long after the language was invented. If you told me at the time that I would one day be writing a series of articles about elegant patterns in JavaScript, I would have laughed you out of the room. I thought of JavaScript as a strange little language that barely even qualified as “real programming.”

Well, a lot has changed in the 20 years since then. I now see in JavaScript what Douglas Crockford saw when he wrote JavaScript: The Good Parts: “An outstanding, dynamic programming language … with enormous, expressive power.”

So, without further ado, here is a wonderful little pattern I’ve been using in my code lately. I hope you come to enjoy it as much as I have.

Please note : I’m pretty sure I did not invent any of this. Chances are I came across it in other people’s code and eventually adopted it myself.

Receive an object, return an object (RORO)

Most of my functions now accept a single parameter of type object and many of them return or resolve to a value of type object as well.

Thanks in part to the destructuring feature introduced in ES2015, I’ve found this to be a powerful pattern. I’ve even given it the silly name, “RORO” because… branding? 🤷‍♂️

Note: Destructuring is one of my favorite features of modern JavaScript. We’re going to be taking advantage of it quite a bit throughout this article, so if you’re not familiar with it, here’s a quick video from Beau Carnes to get you up to speed.

Here are some reasons why you’ll love this pattern:

Named parameters
Cleaner default parameters
Richer return values
Easy function composition

Let’s look at each one.

Named Parameters

Suppose we have a function that returns a list of Users in a given Role and suppose we need to provide an option for including each User’s Contact Info and another option for including Inactive Users, traditionally we might write:

function findUsersByRole (
  role,
  withContactInfo,
  includeInactive
) {...}

A call to this function might then look like:

findUsersByRole(
  'admin',
  true,
  true
)

Notice how ambiguous those last two parameters are. What does “true, true” refer to?

What happens if our app almost never needs Contact Info but almost always needs Inactive Users? We have to contend with that middle parameter all the time, even though it’s not really relevant (more on that later).

In short, this traditional approach leaves us with potentially ambiguous, noisy code that’s harder to understand and trickier to write.

Let’s see what happens when we receive a single object instead:

function findUsersByRole ({
  role,
  withContactInfo,
  includeInactive
}) {...}

Notice our function looks almost identical except that we’ve put braces around our parameters. This indicates that instead of receiving three distinct parameters, our function now expects a single object with properties named role, withContactInfo, and includeInactive.

This works because of a JavaScript feature introduced in ES2015 called Destructuring.

Now we can call our function like this:

findUsersByRole({
  role: 'admin',
  withContactInfo: true,
  includeInactive: true
})

This is far less ambiguous and a lot easier to read and understand. Plus, omitting or re-ordering our parameters is no longer an issue since they are now the named properties of an object.

For example, this works:

findUsersByRole({
  withContactInfo: true,
  role: 'admin',
  includeInactive: true
})

And so does this:

findUsersByRole({
  role: 'admin',
  includeInactive: true
})

This also makes it possible to add new parameters without breaking old code.

One important note here is that if we want all the parameters to be optional, in other words, if the following is a valid call…

findUsersByRole()

… we need to set a default value for our parameter object, like so:

function findUsersByRole ({
  role,
  withContactInfo,
  includeInactive
} = {}) {...}

An added benefit of using destructuring for our parameter object is that it promotes immutability. When we destructure the object on its way into our function we assign the object’s properties to new variables. Changing the value of those variables will not alter the original object.

Consider the following:

const options = {
  role: 'Admin',
  includeInactive: true
}

findUsersByRole(options)

function findUsersByRole ({
  role,
  withContactInfo,
  includeInactive
} = {}) {
  role = role.toLowerCase()
  console.log(role) // 'admin'
  ...
}

console.log(options.role) // 'Admin'

Even though we change the value of role the value of options.role remains unchanged.

It’s worth noting that destructuring makes a_ shallow _copy so if any of the properties of our parameter object are of a complex type (e.g. array or object) changing them would indeed affect the original.

Cleaner Default Parameters

With ES2015 JavaScript functions gained the ability to define default parameters. In fact, we recently used a default parameter when we added ={} to the parameter object on our findUsersByRole function above.

With traditional default parameters, our findUsersByRole function might look like this.

function findUsersByRole (
  role,
  withContactInfo = true,
  includeInactive
) {...}

If we want to set includeInactive to true we have to explicitly pass undefined as the value for withContactInfo to preserve the default, like this:

findUsersByRole(
  'Admin',
  undefined,
  true
)

How hideous is that?

Compare it to using a parameter object like so:

function findUsersByRole ({
  role,
  withContactInfo = true,
  includeInactive
} = {}) {...}

Now we can write…

findUsersByRole({
  role: ‘Admin’,
  includeInactive: true
})

… and our default value for withContactInfo is preserved.

BONUS: Required Parameters

How often have you written something like this?

function findUsersByRole ({
  role,
  withContactInfo,
  includeInactive
} = {}) {
  if (role == null) {
    throw Error(...)
  }
  ...
}

Note: We use double equals (==) above to test for both null and undefined with a single statement.

What if I told you that you could use default parameters to validate required parameters instead?

First, we need to define a requiredParam() function that throws an Error.

Like this:

function requiredParam (param) {
  const requiredParamError = new Error(
   `Required parameter, "${param}" is missing.`
  )

  // preserve original stack trace
  if (typeof Error.captureStackTrace === ‘function’) {
    Error.captureStackTrace(
      requiredParamError,
      requiredParam
    )
  }

  throw requiredParamError
}

I know, I know. requiredParam doesn’t RORO. That’s why I said many of my functions — not all .

Now, we can set an invocation of requiredParam as the default value for role, like so:

function findUsersByRole ({
  role = requiredParam('role'),
  withContactInfo,
  includeInactive
} = {}) {...}

With the above code, if anyone calls findUsersByRole without supplying a role they will get an Error that says Required parameter, “role” is missing.

Technically, we can use this technique with regular default parameters as well; we don’t necessarily need an object. But this trick was too useful not to mention.

Richer Return Values

JavaScript functions can only return a single value. If that value is an object it can contain a lot more information.

Consider a function that saves a User to a database. When that function returns an object it can provide a lot of information to the caller.

For example, a common pattern is to “upsert” or “merge” data in a save function. Which means, we insert rows into a database table (if they do not already exist) or update them (if they do exist).

In such cases, it would be handy to know wether the operation performed by our Save function was an INSERT or an UPDATE. It would also be good to get an accurate representation of exactly what was stored in the database, and it would be good to know the status of the operation; did it succeed, is it pending as part of a larger transaction, did it timeout?

When returning an object, it’s easy to communicate all of this info at once.

Something like:

async saveUser({
  upsert = true,
  transaction,
  ...userInfo
}) {
  // save to the DB
  return {
    operation, // e.g 'INSERT'
    status, // e.g. 'Success'
    saved: userInfo
  }
}

Technically, the above returns a Promise that resolves to an object but you get the idea.

Easy Function Composition

“Function composition is the process of combining two or more functions to produce a new function. Composing functions together is like snapping together a series of pipes for our data to flow through.” — Eric Elliott

We can compose functions together using a pipe function that looks something like this:

function pipe(...fns) {
  return param => fns.reduce(
    (result, fn) => fn(result),
    param
  )
}

The above function takes a list of functions and returns a function that can apply the list from left to right, starting with a given parameter and then passing the result of each function in the list to the next function in the list.

Don’t worry if you’re confused, there’s an example below that should clear things up.

One limitation of this approach is that each function in the list must only receive a single parameter. Luckily, when we RORO that’s not a problem!

Here’s an example where we have a saveUser function that pipes a userInfo object through 3 separate functions that validate, normalize, and persist the user information in sequence.

function saveUser(userInfo) {
  return pipe(
    validate,
    normalize,
    persist
  )(userInfo)
}

We can use a rest parameter in our validate, normalize, and persist functions to destructure only the values that each function needs and still pass everything back to the caller.

Here’s a bit of code to give you the gist of it:

function validate(
  id,
  firstName,
  lastName,
  email = requiredParam(),
  username = requiredParam(),
  pass = requiredParam(),
  address,
  ...rest
) {
  // do some validation
  return {
    id,
    firstName,
    lastName,
    email,
    username,
    pass,
    address,
    ...rest
  }
}

function normalize(
  email,
  username,
  ...rest
) {
  // do some normalizing
  return {
    email,
    username,
    ...rest
  }
}

async function persist({
  upsert = true,
  ...info
}) {
  // save userInfo to the DB
  return {
    operation,
    status,
    saved: info
  }
}

To RO or not to RO, that is the question

I said at the outset, most of my functions receive an object and many of them return an object too.

Like any pattern, RORO should be seen as just another tool in our tool box. We use it in places where it adds value by making a list of parameters more clear and flexible and by making a return value more expressive.

If you’re writing a function that will only ever need to receive a single parameter, then receiving an object is overkill. Likewise, if you’re writing a function that can communicate a clear and intuitive response to the caller by returning a simple value, there is no need to return an object.

An example where I almost never RORO is assertion functions. Suppose we have a function isPositiveInteger that checks wether or not a given parameter is a positive integer, such a function likely wouldn’t benefit from RORO at all.

If you enjoyed this article, please tap the ♥️ icon to help spread the word. And if you want to read more stuff like this, please sign up for my Dev Mastery newsletter below.

Sign up to the DevMastery Newsletter

I keep your info private and I NEVER spam.