You are viewing the Articles in the APIs Category

Simplified Error Handling with Error Causes

Exception handling is a critical aspect to ensuring the reliability and resilience of a system. Perhaps of equal importance is the ability for developers to easily debug exception traces back to a root cause. In JavaScript, however, traditionally this process has often required rather convoluted solutions which lead to intricate patterns that ultimately continued to obscure the underlying root cause. Fortunately, with the introduction of the error.cause property, JavaScript debugging has now taken a significant step forward towards simplifying this process, providing native capabilities which facilitate improved error traceability.

In the legacy paradigm, JavaScript’s error handling was akin to a labyrinth, often requiring developers to traverse a complex maze of stack traces in order to pinpoint the origin of an issue. This often necessitated verbose logging mechanisms, which, while somewhat effective, still lacked fundamental standardization and tended to introduce additional layers of complexity which must be integrated within a system, and understood by team members.

While error cause contexts have been available in numerous other languages such as Rust/WASM, Python, etc. in JavaScript, historically speaking, such a facility has been unavailable. Thus, to mitigate these short-comings, developers would need to resort to basic workarounds such as appending custom properties to re-thrown errors or appending error messages. Although these solutions provided a makeshift bridge to identify error causes, they were rather convoluted at best, and often led to fragmented and inconsistent implementation which never truly solved the problem at hand.

The error.cause property heralds a new era, providing a streamlined approach to attach and propagate the underlying cause of an error, offering a standardized approach for encapsulating the origin of subsequent errors.

Consider the traditional approach where a custom property might have been used to include information related to the originating error:

With error.cause, the same can be now achieved natively while retaining the full stack trace back to the origin root cause:

The benefits of adopting error.cause are manifold, resulting in a significant improvement to Developer Experience though native error traceability. A few key benefits include:

Clarity: Provides a clear lineage of errors, akin to a well-documented review process, making it much easier to understand the flow of exceptions.

Consistency: Promotes a more uniform error handling mechanism across applications.

Simplicity: Reduces the need for additional error handling constructs, streamlining error propagation and handling.

As with countless other language enhancements, the introduction of the error.cause property is a testament to JavaScript’s evolution, offering developers a robust and simplified error handling mechanism; supporting more reliable facility for error tracing, reshaping the way debugging and exception management can be approached.

Benefits of JavaScript Generators

JavaScript Symbols

One of the more nuanced features introduced in ES6 is that of Generator functions. Generators offer a powerful, yet often misunderstood mechanism for controlling the flow of operations, allowing developers to implement solutions with improved readability and efficiency. This article briefly delves into a few of the benefits that JavaScript Generators have to offer, elucidating on their purpose, functionality, and specific scenarios which can benefit from their usage.

A Generator function is a special type of function that can pause execution and subsequently resume at a later time, making it quite valuable for handling asynchronous operations as well as many other use cases. Unlike regular functions which run to completion upon invocation, Generator functions return an Iterator through which their execution can be controlled. It is important to note that while generators facilitate asynchronous operations, they do so by yielding Promises and require external mechanisms, such as async/await or libraries, to handle the asynchronous resolution.

Generators are defined with the function keyword followed by an asterisk (*); i.e. (function*), and are instantiated when called, but not executed immediately. Rather, they wait for the caller to request the next result. This is achieved using the Iterator.next() method, which resumes execution until the next yield statement is encountered, or the generator function returns.

As mentioned, Generator functions return an Iterator, therefore, all functionality of Iterables are available to them, such as for...of loops, destructuring, ...rest parameters, etc.:

Generators allow for the creation of custom iteration logic, such as generating sequences without the need to pre-calculate the entire set. For example, one can generate a Fibonacci sequence using generators as follows:

Generators have the ability to maintain state between yields, thus they are quite useful for managing stateful iterations. This feature can be leveraged in scenarios such as those which require pause and resume logic based on runtime conditions. For instance:

It may initially seem confusing as to how the value passed to game.next(value) is referenced within the Generator function. However, it is important to understand how this mechanism works as it is a core feature of generators, allowing them to interact dynamically with external input. Below is a breakdown outlining this behavior in the context of the above example:

  1. Starting the Generator: When game.next() is first called, the gameState generator function begins execution until it reaches the first yield statement. This initial call starts the generator but does not yet pass any value into it, as the generator is not yet paused at a yield that could receive a value.
  2. Pausing Execution: The yield statement pauses the generator’s execution and waits for the next input to be provided. This pausing mechanism is what differentiates generators from regular functions, allowing for a two-way exchange of values.
  3. Resuming with a Value: After the generator is initiated and paused at a yield, calling game.next(value) resumes execution, passing the value into the generator. This passed value is received by the yield expression where the generator was paused.
  4. Processing and Pausing Again: Once the generator function receives the value and resumes execution, it processes operations following the yield until it either encounters the next yield (and pauses again, awaiting further input), reaches a return statement (effectively ending the generator’s execution), or completes its execution block.

This interactive capability of generators to receive external inputs and potentially alter their internal state or control flow based on those inputs is what makes them particularly powerful for tasks requiring stateful iterations or complex control flows.

In addition to yielding values with yield, generators have a distinct behavior when it comes to the return statement. A return statement inside a generator function does not merely exit the function, but instead, it provides a value that can be retrieved by the iterator. This behavior allows generators to signal a final value before ceasing their execution.

When a generator encounters a return statement, it returns an object with two properties: value, which is the value specified by the return statement, and done, which is set to true to indicate that the generator has completed its execution. This is different from the yield statement, which also returns an object but with done set to false until the generator function has fully completed.

This example illustrates that after the return statement is executed, the generator indicates it is done, and no further values can be yielded. However, the final value returned by the generator can be used to convey meaningful information or a result to the iterator, effectively providing a clean way to end the generator’s execution while also returning a value.

Generators also provide a return() method that can be used to terminate the generator’s execution prematurely. When return() is called on a generator object, the generator is immediately terminated and returns an object with a value property set to the argument provided to return(), and a done property set to true. This method is especially useful for allowing clients to cleanly exit generator functions, such as for ensuring resources are released appropriately, etc..

In this example, after the first yield is consumed, return() is invoked on the generator. This action terminates the generator, returns the provided value, and sets the done property of the generator to true, indicating that the generator has completed and will no longer yield values.

This capability of generators to be terminated early and cleanly, returning a specified value, provides developers fine-grained control over generator execution.

Generators provide a robust mechanism for error handling, allowing errors to be thrown back into the generator’s execution context. This is accomplished using the generator.throw() method. When an error is thrown within a generator, the current yield expression is replaced by a throw statement, causing the generator to resume execution. If the thrown error is not caught within the generator, it propagates back to the caller.

This feature is particularly useful for managing errors in asynchronous operations, enabling developers to handle errors in a synchronous-like manner within the asynchronous control flow of a generator.

This example illustrates how generator.throw() can be used to simulate error conditions and test error handling logic within generators. It also shows how generators maintain their state and control flow, even in the presence of errors, providing a powerful tool for asynchronous error management.

One particularly interesting feature of Generators is that they can be composed of other generators via the yield* operator.

The ability to compose Generators allows for implementing various levels of abstraction and reuse, making their usage much more flexible.

Generators can be used for many purposes, ranging from basic use-cases such as generating a sequence of numbers, to more complex scenarios such as handling streams of data so as to allow for processing input as it arrives. Through the brief examples above, we’ve seen how Generators can improve the way we, as developers, approach implementing solutions for asynchronous programming, iteration, and state management.

Unique Identifiers with JavaScript Symbols

JavaScript Symbols

The introduction of Symbols in ES6 marked a significant milestone, offering developers a new primitive type to enhance code clarity, privacy, and interoperability.

At their core, Symbols serve as unique, immutable identifiers, making them quite valuable for many use-cases. This article delves into the benefits of JavaScript Symbols, illustrating how they can be leveraged to provide implementations which are more secure and mitigate the risk of unforeseen conflicts.

Before we explore the benefits of Symbols, it’s important to first understand what the actually are. In JavaScript, a Symbol is a primitive data type, just like string, number, boolean, etc.. However, what sets Symbols apart is their guarantee of uniqueness. Every time you create a Symbol, it is distinct from all other Symbols, even if they share the same value.

Creating a Symbol is rather straightforward:

Despite having the same value, name1 and name2 are not equal.

There are numerous benefits to using Symbols, especially when using them within Objects.

Ensuring Property Uniqueness:
One of the most prominent benefits of Symbols is their role in ensuring property uniqueness within objects. This uniqueness is particularly beneficial in avoiding property name collisions, especially when working with complex implementations or when integrating third-party libraries.

Symbol Properties are Not Enumerated:
Another advantage of Symbols is that properties keyed by Symbols are not enumerated in for...in, or Object.keys(), Object.values(), or Object.entries(). This characteristic can be used to hide certain properties from the enumeration process, thus providing a form of property privacy.

Facilitating Meta-Programming:
Symbols play a pivotal role in JavaScript’s meta-programming capabilities. Several well-known Symbols, are used to customize the behavior of certain language constructs. For example, Symbol.iterator allows an object to define its iteration behavior, enabling it to be compatible with both the for...of loop and spread operator.

Enhanced Debugging:
Symbols can also aid in debugging by providing a descriptive identifier for otherwise anonymous properties. When you create a Symbol with a Symbol description, this description is shown in debugging tools, making it easier to identify and differentiate between various Symbols.

JavaScript Symbols present a robust mechanism for ensuring uniqueness, enhancing privacy, and empowering meta-programming within applications. By leveraging Symbols, developers can avoid common pitfalls such as property name collisions and inadvertently exposing internal properties, leading to more secure, maintainable, and sophisticated deigns. As JavaScript continues to evolve, understanding and utilizing Symbols will undoubtedly become an essential skill for modern web developers.

Quick Tip: Backbone Collection Validation

Often times I find the native Backbone Collection implementation to be lacking when compared to it’s Backbone.Model counterpart. In particular, Collections generally lack in terms of direct integration with a backend persistence layer, as well as the ability to validate models within the context of the collection as a whole.

Fortunately, such short comings can easily be circumvented due to the extensibility of Backbone’s design as a generalized framework. In fact, throughout my experience utilizing Backbone, I can assert that there has yet to be a problem I have come across which I was unable to easily solve by leveraging one of the many Backbone extensions, or, more often than not, by simply overriding Backbone’s default implementation of a given API.

Validating Collections

Perhaps a common use-case for validating a collection of Models can be found when implementing editors which allow for adding multiple entries of a given form section (implemented as separate Views), whereby each section has a one-to-one correlation with an individual model. Rather than invoke validation on models from each individual view, and manage which model’s are in an invalid state from the context of a composite view, it can be quite useful to simply validate the collection from the composite view which, in turn, results in all models being validated and their associated views updating accordingly.

Assuming live validation is not being utilized, validation is likely to occur when the user submits the form. As such, it becomes necessary to validate each model after their views have updated them as a result of the form being submitted. This can be achieved quite easily by implementing an isValid method on the collection which simply invokes isValid on each model within the collection (or optionally, against specific models within the collection). A basic isValid implementation for a Collection is as follows:

As can be seen in the above example, the Collection’s isValid method simply invokes isValid on it’s models. This causes each model to be re-validated which, in turn, results in any invalid models triggering their corresponding invalidation events, allowing for views to automatically display validation indicators, messages, and the like; particularly when leveraging the Backbone.Validation Plugin.

This example serves well to demonstrate that, while Backbone may not provide everything one could ever ask for “out of the box”, it does provide a design which affords developers the ability to quickly, easily, and effectively extend the native framework as needed.

Fluent APIs and Method Chaining

Of the vast catalog of Design Patterns available at our disposal, often times I find it is the simpler, less prominent patterns which are used quite frequently, yet recieve much less recognition; a good example of which being the Method Chaining Pattern.

Method Chaining

The Method Chaining Pattern, as I have come to appreciate it over the years, represents a means of facilitating expressiveness and fluency when used articulately, and mere convenience in it’s less sophisticated use-cases.

Design Considerations

When considering Method Chaining, one should take heed not to simply use the pattern as merely syntactic sugar from which writing fewer lines of code can be achieved; but rather, Method Chaining should be used, perhaps more appropriately, as a means of implementing Fluent APIs which, in turn, allow for writing more concise expressions. By design, such expressions can be written, and thus read, in much the same way as natural language, though they need not be the same from a truly lexical perspective.

The resulting terseness afforded by Method Chaining, while convenient, is in most cases not in-of-itself a reason alone for leveraging the pattern.

Implementation

Method Chaining, when considered purely from an implementation perspective, is perhaps the simplest of all design patterns. It’s basic mandate simply prescribes returning a reference to the object on which a method is being called (in most languages, JavaScript in particular, the this pointer).

Consider the following (intentionally contrived) example:

As can be seen, implementing Method Chaining requires nothing more than simply having methods return a reference to this.

API Simplicity

Method Chaining is typically used when breaking from traditional Command Query Seperation (CQS) principles. The most common example being the merging of both getters (Queries) and setters (Commands). I especially like this technique, as, aside from being very easy to implement, it allows for an API to be used in a more contextual manner from the developers perspective as oppossed to that specified by the API designer’s preconceptions of how the API will be used. For example:

As can be seen, the message method serves as both a getter and setter, allowing users of the API to determine how the method should be invoked based on context, as well as affording developers the convenience of needing only to remember a single method name. This technique is used quite heavily in many JavaScript libraries and has undoubtedly contributed to their success.

We could further expand on this concept by determining a method’s invocation context based on the arguments provided, or the types of specific arguments, thus, in turn, merging various similar methods based on a particular context.

An important design recommendation to consider is that if you are writing an API which violates CQS (which is quite fine IMHO), as always, API consistency is important, thus all getters and setters should be implemented in the same manner.

Fluency

As was mentioned, in most cases, Method Chaining is leveraged to facilitate APIs which are intended to be used fluently (e.g. an Internal DSL). Such implementations typically provide methods which, by themselves, may have little meaning; however, when combined, allow for writing expressions which are self-descibing and make logical sense to users of the API.

For example, consider the way one might describe a Calendrical Event:

Vacation, begins June 21st, ends July 5th, recurs Yearly.

We can easily implement a Fluent API such that the above grammar can be emulated in code as follows:

The same methods can also be chained in different combinations, yet yield the same value:

Given the above example, we could further improve on the fluency of the implementation by adding intermediate methods which can, by themselves, simply serve to aid in readability, or, provide an alternate modifier for chaining:

When implementing Fluent APIs, we can design such that different logical chaining combinations can yield the same result, thus affording users of the API the convenience of determining the most appropriate expressions based on context or personal preference, even grammatically so. Illogical chaining combinations can be handled by either throwing an exception, or they can simply be ignored based on the context of a preceding invocation – though, of course, one should aim to avoid designs which allow for illogical chaining.

The Ubiquitous Example – jQuery

While Method Chaining and Fluent APIs, as with most design patterns, are language agnostic, in the JavaScript world perhaps the most well known implementation is the jQuery API; for example:

In addition to jQuery, there are numerous additional JavaScript Method Chaining and Fluent APIs of note, Jasmine in particular has a very expressive API which aligns excellently with it’s design goals. The various libraries which implement the Promises/A spec also provide very clear and concise Fluent APIs.

Concluding Thoughts

Over the years I have leveraged Method Chaining to facilitate the design of Fluent APIs for various use-cases. The two patterns, when combined, can be especially useful when designing Internal DSLs; either third-party libraries, or APIs specific to a particular business domain.

Invoking Native Mobile Applications with URI Schemes

In a previous article, I outlined how the native iOS Keyboard and it’s behaviors can be managed with HTML5 input types. In addition to this, iOS, Android and most A-Grade Mobile platforms implement standard URI Schemes (or parts thereof), which allow for easily launching native applications.

URI Schemes

When considering URI Schemes, more commonly (though incorrectly) referred to as protocols, one typically thinks in terms of the more ubiquitous schemes: http, ftp, file, mailto, about, data:uri and so forth. However, as with these and other common URI Schemes, there are additional schemes which allow for various practical applications in the context of Mobile Web Apps; the most common of which being the ability to invoke a platform’s native phone or messaging application, respectively.

URI Schemes and Mobile Devices

In the context of Mobile Web Applications, the tel, and sms URI Schemes are perhaps the most common and applicable; providing a simple means of invoking their corresponding native applications. The following are basic examples which work across all major mobile platforms.

The tel URI Scheme

The tel URI Scheme allows for launching a device’s native Phone application in the context of the phone number specified:

The sms URI Scheme

The sms URI Scheme allows for launching a device’s native Messaging application to send an sms message, or to send an sms message to the phone number specified:

As can be seen in the above examples, hyphens are used in the same manner as one would typically specify a phone number; however, use of visual separators are purely optional – they can be used to aid in readability if desired, but are otherwise ignored when parsing the URI.

As a general best practice, one should take care to ensure both tel and sms URI Schemes are defined in lowercase, so as to ensure portability across platforms. Additionally, it is important to note that the sms scheme is not implemented to completion against it’s formal definition on any platform (see section 2.2 of rfc5724); thus, an sms message body, or sending an sms message to multiple recipients is not supported.

While there is nothing particularly ground breaking about these URI Schemes, or technically complex for that matter, they do prove to be quite useful in the context of Mobile Web Applications. As such, they are certainly worth noting as each can be leveraged to improve the usability of an application.