You are currently browsing the JavaScript archives.

Simplifying Designs with Parameter Objects

Tuesday, January 22nd, 2013

Recently, while reading the HTML5 Doctor interview with Ian Hickson, when asked what some of his regrets have been over the years, the one he mentions, rather comically so as being his “favorite mistake”, also happened to be the one which stood out to me most; that is, his disappointment with pushState; specifically, the fact that of the three arguments accepted, the second argument is now ignored.

I can empathize with his (Hixie’s) frustration here; not simply because he is one of the most influential figures on the web – particularly for his successful work surrounding CSS, HTML5, and his responsibilities at the WHATWG in general – but rather, it is quite understandable how such a seemingly insignificant design shortcoming would bother such an obviously talented individual, especially considering the fact that pushState's parameters simply could not be changed due to the feature being used prior to completion. Indeed, the Web Platform poses some very unique and challenging constraints under which one must design.

While the ignored pushState argument is a rather trivial issue, I found it to be of particular interest as I often employ Parameter Objects to avoid similar design issues.

Parameter Objects

The term “Parameter Object” is one I use rather loosely to describe any object that simply serves as a wrapper from which all arguments are provided to a function. In the context of JavaScript, object literals serve quite well in this capacity, even for simpler cases where a function would otherwise require only a few arguments of the same type.

Parameter Objects are quite similar to that of an “Options Argument” – a pattern commonly implemented by many JavaScript libraries to simplify providing optional arguments to a function; however, I tend to use the term Parameter Objects more broadly to describe a single object parameter from which all arguments are provided to a function, optional arguments included. The two terms are often used interchangeably to describe the same pattern. However, I specifically use the term Options Argument to describe a single object which is reserved exclusively for providing optional arguments only, and is always defined as the last parameter of a function, proceeding all required arguments.

Benefits

Parameter Objects can prove beneficial in that they afford developers the ability to defer having to make any final design decisions with regard to what particular inputs are accepted by a function; thus, allowing an API to evolve gracefully over time.

For instance, using a Parameter Object, one can circumvent the general approach of implementing functions which define a fixed, specific order of parameters. As a result, should it be determined that any one particular parameter is no longer needed, API designers need not be concerned with requiring calling code to be refactored in order to allow for the removal of the parameter. Likewise, should any additional parameters need to be added, they can simply be defined as additional properties of the Parameter Object, irrespective of any particular ordering of previous parameters defined by the function.

As an example, consider a theoretical rotation function which defines five parameters:

Using a Parameter Object, we can refactor the above function to the following:

Should we wish to remove a parameter from the function, doing so simply requires making the appropriate changes at the API level without changing the actual signature of the function (assuming of course, there are no specific expectations already being made by calling code regarding the argument to be removed). Likewise, should additional parameters need to be added, such as a completion callback, etc., doing so, again, only requires making the appropriate API changes, and would not impact current calling code.

Additionally, taking these potential changes as an example, we can also see that with Parameter Objects, implementation specifics can be delegated to the API itself, rather than client code insofar that the provided arguments can be used to determine the actual behavior of the function. In this respect, Parameter Objects can also double as an Options Argument. For example, should the arguments required to perform a 3D rotation be omitted from the Parameter Object, the function can default to a 2D rotation based on the provided arguments, etc.

Convenience

Parameter Objects are rather convenient in terms of there being less mental overhead required than that of a function which requires ordered arguments; this is especially true for cases where a function defines numerous parameters, or successive parameters of the same type.

Since code is generally read much more frequently than it is written, it can be easier to understand what is being passed to a function when reading explicit property names of an object, in which each property name maps to a parameter name, and each property value maps to parameter argument. This can aid in readability where it would otherwise require reading the rather ambiguous arguments passed to a function. For example:

With Parameter Objects it becomes more apparent as to which arguments correspond to each specific parameter:

As mentioned, if a function accepts multiple arguments of the same type, the likelihood that users of the API may accidentally pass them in an incorrect order increases. This can result in errors that are likely to fail silently, possibly leading to the application (or a portion thereof) becoming in an unpredictable state. With Parameter Objects, such unintentional errors are less likely to occur.

Considerations

While Parameter Objects allow for implementing flexible parameter definitions, the arguments for which being provided by a single object, they are obviously not intended as a replacement for normal function parameters in that should a function need only require a few arguments, and the function’s parameters are unlikely to change, then using a Parameter Object in place of normal function parameters is not recommended. Also, perhaps one could make the argument that creating an additional object to store parameter/argument mappings where normal arguments would suffice adds additional or unnecessary overhead; however, considering how marginal the additional footprint would be, this point is rather moot as the benefits outweigh the cost.

A Look at pushState’s Parameters

Consider the parameters defined by pushState:

  1. data: Object
  2. title: String
  3. url: String

The second parameter, title, is the parameter of interest here as it is no longer used. Thus, calling push state requires passing either null or an empty String (recommended) as the second argument (i.e. title) before one can pass the third argument, url. For example:

Using a Parameter Object, pushState could have been, theoretically, implemented such that only a single argument was required:

  1. params: Object
    • data: Object
    • title: String
    • url: String

Thus, the ignored title argument could be safely removed from current calling code:

And simply ignored in previously implemented calls:

As can be seen, the difference between the two is quite simple: the specification for pushState accepts three arguments, whereas the theoretical Parameter Object implementation accepts a single object as an argument, which in turn provides the original arguments.

Concluding Thoughts

I certainly do not assume to understand the details surrounding pushState in enough detail to assert that the use of a Parameters Object would have addressed the issue. Thus, while this article may reference pushState as a basic example to illustrate how the use of a Parameter Object may have proved beneficial, it is really intended to highlight the value of using Parameter Objects from a general design perspective, by describing common use-cases in which they can prove useful. As such, Parameter Objects provide a valuable pattern worth considering when a function requires flexibility.

Basic Dependency Injection with RequireJS

Saturday, December 15th, 2012

Recently, I was having a conversation about the basic concepts of IoC/DI, and, specifically, how they pertain to modern (single page) JavaScript Web Applications. This discussion was quite interesting, and so I felt inclined to share some thoughts on the subject with a wider audience.

Dependency Injection in JavaScript

Being a dynamic language, when designing JavaScript based architectures, in comparison to architectures which are under the constraints of a statically typed language, one is typically less inclined to consider the relevance of, or immediate need for, a complete IoC container. Of course, context is key, and so there are certainly JavaScript applications which can benefit from an IoC container (such as wire.js). As such, it would not be prudent for one to suggest otherwise; but rather, this is simply to say that for the majority of JavaScript applications, standard AMD loaders provide a sufficient means of managing dependencies; as the rigidness inherent to statically typed languages which IoC containers help manage are generally less relevant to dynamic languages.

With that being said, while a robust IoC container may not be necessary for the majority of JavaScript applications, it is quite important to emphasize the benefits of employing basic dependency management and Dependency Injection; as this is an essential design characteristic which is critical to the success and overall maintainability of large scale client-side web applications.

Facilitating Code Reuse

Anyone who has been responsible for developing and maintaining specific core features across multiple applications is likely to understand that the ability to facilitate reuse of JavaScript modules is crucial. This is particularly important in the context of architectures which must account for the ability to support mulitple implementations of the same application across different form-factors; for, the ability to manage and configure dependencies can prove paramount; allowing for a framework upon which various form-factor specific implementations of an application can be supported.

In addition to this, as one might expect, having the flexibility necessary for configuring dependencies lends itself, quite naturally so, to various unit testing scenarios.

Configuring Dependencies with RequireJS

Though not always immediately apparent, applications leveraging RequireJS are essentially using a basic form of Dependency Injection out of the box – even if not in the most purist sense of the term. However, the simple matter of mapping module names to module implementations can be considered, in-of-itself, a basic form of Dependency Injection, or perhaps, one could argue this as being more of a Service Locator, as RequireJS does not instantiate dependencies on a clients behalf. Regardless of the preferred classification, this mechanism of defining dependencies is quite important, as it affords developers the ability to change module implementations as desired without the need to change client code. Of course, such modules must adhere to a specific contract (interface) so as to ensure clients which depend on specific named modules receive the expected API.

Explicit Dependencies

Consider a rather contrived example of a shared Application module which is used across two separate applications; one for Mobile and one for Desktop; with the Application module having a dependency on an AppHelper module:

Both the Mobile and Desktop applications can easily map the AppHelper module to a context specific implementation via their respective main.js configurations:

Based on the above, it is rather evident that the AppHelper module is mapped to the appropriate application specific implementation; MobileHelper for mobile, and DesktopHelper for desktop. Additional context specific APIs can just as easily be defined, and thus provided as dependencies to other modules as needed using this very simple pattern.

Implicit Dependencies

Dependencies need not always be explicit, but rather they can also be implicitly mapped based on the path to which each application’s main.js configuration resides, or based on the configured baseUrl path.

For instance, given the above example, we can map a Templates Module, and implicitly inject the path to each context specific template based on the application’s default path, or baseUrl path:

As can be seen, each application’s main.js defines a Templates module and a TemplateSource module, respectively, with each being shared amongst both the Mobile and Desktop specific applications. The Templates and TemplateSource modules are defined as follows:

While both the Mobile and Desktop applications may share the same Templates and TemplateSource modules, the specific implementation of the templates loaded from TemplateSource is determined via each application’s base path; thus, the path to app/templates/some-view.tpl automatically resolves to the context specific template; i.e.: mobile/app/templates/some-view.tpl for Mobile, and desktop/app/templates/some-view.tpl for Desktop.

Concluding Thoughts

While the above examples are rather basic, they do serve well to demonstrate just how easily one can design for module reuse across different applications with RequireJS, which itself allows for much more robust configurations of modules; such as loading context specific modules at runtime, augmenting modules for differing contexts with mixins, providing third-party libraries based on a particular form-factor (e.g. jQuery for Desktop, Zepto for Mobile, etc.), and more.

You can clone the above example here.

Quick Tip: Chrome Developer Tools Shortcut Keys

Wednesday, November 21st, 2012

Sometimes it is the more subtle, less obvious features provided by tools which prove to be surprisingly useful. Interestingly, while such features can save developers considerable time and effort, they are often much less apparent, and thus, occasionally overlooked when compared to their main counterparts.

A noteworthy example of some very simple, yet extremely useful features can be found in just a few of the basic Chrome Developer Tools shortcut keys. Below is a brief description of the most convenient shortcuts I find myself using regularly.

Go to Source (Cmd-O)

Perhaps the most useful short-cut available in the sources panel, Cmd-O allows one to quickly search for a specific source file (thanks to @augiemarcello for this one):
Chrome Developer Tools Command-O

Show Functions (Cmd-shift-O)

Another extremely useful feature in the Sources Panel, Cmd-shift-O displays a list of all functions and their corresponding line numbers within the current source file:
Chrome Developer Tools Command-Shift-O

Clear Console (Cmd-K/)

Clears the console when in focus:
Chrome Developer Tools Command-k

Previous/Next Panel (Cmd-[ / Cmd-])

Toggles between Developer Tools Panels (e.g. Elements, Resources, Network, Sources etc.):
Chrome Developer Tools Command-[]

There are quite a few additional shortcut keys available in Chrome Developer Tools, and Jared has done a excellent job of providing a Devtools cheat sheet. I highly recommend trying some of them out; committing to memory those which you find most useful – and sharing them with others as well.

Determining if an object is empty with Underscore / Lo-dash

Saturday, August 18th, 2012

When leveraging the utilities provided by Underscore or Lo-dash, determining if an Array, String or Object is empty is quite simple via the isEmpty() method.

The isEmpty() method and Objects

In the context of an Object, it is important to keep in mind that _.isEmpty() is implemented such that it determines an Object as being empty in a literal sense. That is, objects are traversed to determine the existence of any own properties – irrespective of their actual values. Thus, _.isEmpty() will return false if an object contains any own properties, even if all property values are undefined, otherwise it will return true.

While these details may seem obvious, it is important to be mindful of them in order to avoid potential false positives when trying to determine if an object’s properties are all undefined.

For example, consider the following object:

Technically, the above object is not empty, as it contains two own properties. Thus, invoking _.isEmpty() with this object will return false, which is correct, though one may have mistakenly assumed it to have returned true since all of the object’s properties are undefined.

Extending Underscore / Lo-dash

With an understanding in mind of how _.isEmpty() is implemented in the context of objects, should one need to determine if an object is empty based on the values of it’s own properties being undefined, a simple extension, such as the following, can be mixed into Underscore or Lo-dash to provide both the default implementation as well as an extended implementation which takes this into account:

Given the above, we can then invoke the original isEmpty implementation, as well as the extended implementation as follows:

The ease with which libraries such as Underscore and Lo-dash allow for adding extensions and overriding default implementations is a key design feature which makes them not only extremely flexible, but also quite enjoyable to work with as well.

Managing Client-side Templates with RequireJS

Sunday, July 15th, 2012

When developing single page web applications, patterns of structure, organization and reuse become ever more important. This especially holds true when there is a need to maintain mulitiple web applications, each of which targeting a specific form factor, while also sharing many of the same underlying core APIs.

In the context of client-side templating, such patterns begin to emerge, quite naturally so, when leveraging RequireJS modules and the RequireJS text plugin.

Template Modules

One specific pattern I have found myself implementing is that of a single Templates Module which provides a centralized location from which all compiled templates within an application can be referenced. A rather simple pattern, Template Modules are only concerned with loading, compiling and providing a public API to access compiled templates; that is, a Templates Module simply requires all external templates, and provides named methods for retrieving the compiled template functions of each.

A basic implementation of a Templates module is as follows (while Handlebars may be used in this example, any template engine would suffice):

The main benefit of implementing a Templates Module is reuse, as different modules can use the same templates without a need for redundantly requiring and compiling the templates themselves. Additionally, Template Modules provide a convenient means of abstracting away the underlying template engine from client code, thus reducing the amount of refactoring needed should the template engine itself ever need to change.

When using the RequireJS Optimizer, each external template will be included in the optomized build and loaded synchronously, and so there is no additional overhead in terms of HTTP requests when requiring each template in a single location.

You can check out a basic example implementation of a Templates Module (in the context of Backbone) here.

JavaScript Comma Delimiter Pattern

Tuesday, June 5th, 2012

Perhaps the most common syntactic error I find myself correcting in JavaScript is that of a simple missing comma separator on new lines. Such marginal oversights can become quite a nuisance to correct time and time again. Fortunately, there is a rather simple pattern which can be used to help avoid these errors with very little effort – only requiring code to be rewritten in a manner that reads more naturally while also being syntactically correct.

Typical missing comma scenario

If we are to consider the most common scenario where a comma is unintentionally omitted (and a subsequent exception is thrown), it can most likely be found within The Single var Pattern (irrespective of any personal preference towards or against the pattern itself).

For example, consider a typical block of code implementing a single var:

The above example, being rather typical and admittedly simple, does not pose much of a maintenance issue itself. However, if one is to refactor these declarations into a different order, add additional declarations, or specify more complex assignments, the probability of a comma being omitted unintentionally or becoming out of place increases.

In addition to The Single var Pattern, object literals are also a good source of occasional commas being omitted unintentionally, especially when nested within additional literals:

A Simple Solution

To help avoid such mistakes altogether, we can simply place commas before declarations, rather than after. At first, this may feel a bit awkward, but in time it becomes quite easy to get used to.

With this in mind, by placing commas first, the above could easily be refactored to the following:

As can be seen in the above example, considering we generally read code left to right, it becomes immediately apparent if a comma is missing.

For instance, take note of which implementation is easier to notice the missing comma:

I suspect most would agree that commas placed before stand out much more, and therefore it becomes much more apparent when one is missing. This appears to be so as the difference between the two is such that with commas placed after one needs to look for what is missing, whereas with commas placed before one sees what is missing.

As humans, our tendency towards patterns in general, and visual patterns in particular can not be understated. As developers, considering patterns are a significant part of our work, we should strive to take advantage of the most natural ones especially, even for things as seemingly marginal as placing comma separators first.