How to use JavaScript Symbols to create unique object properties

JavaScript is a powerful and versatile language, but even seasoned developers can find themselves overwhelmed by its subtle nuances. One of these subtle, but very much useful  features is the Symbol type. Introduced in ECMAScript 6 (ES6), Symbols don't often get talked about, but they play a pretty important role in creating unique object properties that can enhance your code. 

In this article, I'll dive deep into JavaScript Symbols, explore how they work, and examine their role in ensuring object property uniqueness. By the end of this post, you’ll have a clear understanding of why and how to use Symbols in your projects.

What Are JavaScript Symbols?

In JavaScript, a Symbol is a primitive data type just like Number, String, or Boolean. However, unlike other primitives, Symbols are unique and immutable, meaning that every time you create a new Symbol, it’s guaranteed to be different from any other Symbol, even if they have the same description. Seems very useful.

Syntax of Symbols

You can create a Symbol using the Symbol() function:

const tmpSymbol = Symbol();

If you want to give your Symbol a description for easier debugging, you can pass a string as an argument:

const tmpSymbol2 = Symbol('description text');

It's important to note that this description is only for debugging purposes and does not affect the Symbol's identity or uniqueness in any way.

Uniqueness of Symbols

The main characteristic of a Symbol is its uniqueness. Consider the following example:

const sym1 = Symbol('sym');
const sym2 = Symbol('sym');

console.log(sym1 == sym2); // false

Even though sym1 and sym2 have the same description, they are completely different Symbols. This inherent uniqueness is what makes Symbols ideal for creating unique property keys in objects.

Why Use Symbols for Object Properties?

In JavaScript, objects are collections of key-value pairs, where keys are typically strings or numbers. However, this can sometimes lead to conflicts, especially in larger projects or when integrating third-party libraries. For instance, if two libraries use the same string as a key, one could inadvertently overwrite the other’s value.

This is where Symbols come in handy. Because Symbols are guaranteed to be unique, they prevent accidental key collisions, ensuring that your object properties remain distinct.

Defining Object Properties with Symbols

Here’s how you can define a Symbol as a key for an object property:

const uniqueKey = Symbol('unique');
const obj = {
  [unique]: 'unique value'
};

console.log(obj[unique]); // unique value

In this example, uniqueKey is a Symbol, which ensures that the property it’s associated with cannot be accidentally overwritten by another property with the same string key.

Hiding Object Properties with Symbols

Symbols can also be used to create "hidden" object properties that are not easily accessible through typical enumeration methods like for...in loops or Object.keys(). This can be particularly useful for storing metadata or private data inside of an object.

Let's take a look at an example:

const sym1 = Symbol('hide');
const obj = {
  visible: 'visible',
  [sym1]: 'hidden'
};

for (let k in obj){
  console.log(k); // logs 'visible', not 'hidden' property
}

console.log(Object.getOwnPropertySymbols(obj)); // logs [Symbol(hidden)]

As you can see, sym1 is not enumerated by for...in or Object.keys(), making it effectively hidden unless you specifically access it.

Well-Known Symbols

JavaScript includes several built-in Symbols known as Well-Known Symbols. These are predefined and used internally by JavaScript to alter the behavior of objects. Some of the most commonly used Well-Known Symbols include:

Symbol.iterator: Used to define the default iterator for an object, enabling it to be used in for...of loops.

Symbol.toStringTag: Allows you to customize the [[ToString]] operation, which controls the default string description of an object.

Symbol.hasInstance: Customizes the behavior of the instanceof operator.

The following is an example of what that looks like using the Symbol.iterator:

Example: Using Symbol.iterator

Let's see how you can make an object iterable using Symbol.iterator:

const iterable = {
  [Symbol.iterator]() {
    let step = 0;

    return {
       next() {
         step++;


        if (step <= 4) {
           return {value: step, done: false};
        }

        else {
           return {done: true};
        }
      }
    }
};


for (let val of iterable){
  console.log(val); // logs the values 1 to 5
}

In this example, Symbol.iterator allows the iterable object to be iterated over in a for...of loop, yielding values from 1 to 5.

When to Use Symbols in JavaScript

Symbols are definitely a powerful feature in JavaScript, but they aren't always the right choice. Here are a few scenarios where Symbols are particularly useful:

Avoiding Property Name Collisions: When working with large codebases or integrating third-party libraries, use Symbols to ensure that your object properties do not accidentally collide with those defined elsewhere.

Creating Non-Enumerable Properties: If you need to store data that should not be easily accessible or enumerated, Symbols provide a way to create hidden properties.

Defining Custom Object Behavior: Use Well-Known Symbols to customize how objects behave in certain contexts, such as iterating or converting to strings.

Conclusion

JavaScript Symbols are a useful feature that allow developers to create truly unique object properties. Whether you're working on complex applications or just looking to prevent accidental property collisions, understanding and utilizing Symbols can lead to cleaner, more maintainable code.