TypeScript Reference : Symbols

Symbols are a unique feature in TypeScript that allow developers to define immutable properties as well as create well-defined object keys. Symbol values are completely unique and cannot be duplicated, making them a powerful tool for creating unique identifiers in an application. In this TypeScript reference, we will explore everything you need to know about symbols and how to use them effectively.

In TypeScript, symbols are created using the Symbol constructor. When a symbol is created, it is completely unique and cannot be compared to any other symbol, even if the symbol has the same name. This uniqueness makes symbols great for use as object keys, where you want to ensure that the key is unique and cannot be accidentally overwritten or accessed by other parts of the code.

Symbols also have a number of built-in properties and methods that can be used to customize their behavior. One such property is the description property, which allows you to provide a human-readable description of the symbol. This can be useful for debugging or for providing additional information about the symbol.

One important thing to note about symbols is that they are completely private and cannot be accessed from outside their scope. This makes them a great choice for creating private members in classes or objects, as they cannot be accessed or modified by other parts of the code.

In conclusion, symbols are a powerful tool in TypeScript for creating unique identifiers and ensuring the immutability of properties. They are completely unique and cannot be duplicated, making them ideal for use as object keys or private members. By understanding the features and behaviors of symbols, developers can take full advantage of them to create more robust and secure TypeScript applications.

What are Symbols?

A symbol is a unique and immutable data type that can be used as an identifier for object properties. It was introduced in ECMAScript 2015 (ES6) and provides a way to create unique keys for object properties.

Symbols are often used as property keys, specifically when creating properties that should be hidden and not accessible through normal object property access methods. They provide a way to define private properties or methods in objects, similar to how private members work in other programming languages.

Creating a Symbol

To create a symbol, you can use the built-in Symbol function. When called, it returns a new unique symbol.

const mySymbol = Symbol();

You can also provide an optional description when creating a symbol, which can be useful for debugging purposes:

const mySymbol = Symbol('My Symbol');

Using Symbols as Property Keys

Symbols can be used as property keys in objects. When using a symbol as a property key, it creates a unique property that is not enumerable in for…in loops and does not show up in Object.getOwnPropertyNames or Object.getOwnPropertySymbols.

Here’s an example:

const mySymbol = Symbol('My Symbol');

const obj = {
[mySymbol]: 'Hello, Symbol!'
};
console.log(obj[mySymbol]); // Output: Hello, Symbol!
console.log(Object.getOwnPropertyNames(obj)); // Output: []
console.log(Object.getOwnPropertySymbols(obj)); // Output: [Symbol(My Symbol)]

In the above example, the symbol mySymbol is used as a property key in the object obj. The value associated with the symbol is ‘Hello, Symbol!’. When accessing the property using obj[mySymbol], it outputs the value ‘Hello, Symbol!’.

The property is not enumerable and does not show up in Object.getOwnPropertyNames(obj), but it does show up in Object.getOwnPropertySymbols(obj).

Symbol Registry

Symbols can be shared and accessed across different parts of an application by using the built-in symbol registry. The symbol registry is a global shared symbol registry that can be accessed using the Symbol.for method.

The Symbol.for method takes a string as an argument and returns a symbol from the registry with the provided key. If the symbol doesn’t exist in the registry, it creates a new symbol and adds it to the registry.

Here’s an example:

const mySymbol = Symbol.for('My Symbol');

const mySymbolAgain = Symbol.for('My Symbol');
console.log(mySymbol === mySymbolAgain); // Output: true

In the above example, the symbols mySymbol and mySymbolAgain reference the same symbol because they were created using the same key (‘My Symbol’). The === operator returns true when comparing the two symbols.

The symbol registry is useful when you want to share symbols between different parts of your application, ensuring that the same symbol is used across different modules.

Overall, symbols in TypeScript provide a way to create unique property keys and define private members in objects. They are a powerful tool for controlling access to properties and methods and are widely used in libraries and frameworks.

Creating Symbols

Symbols in TypeScript can be created using the Symbol() function, which returns a unique symbol value. By convention, the Symbol() function takes an optional string parameter that can be used as a description for debugging purposes:

const sym1 = Symbol();

const sym2 = Symbol('foo');

The Symbol() function always returns a unique symbol value, even if the description string is the same:

const sym1 = Symbol('foo');

const sym2 = Symbol('foo');
console.log(sym1 === sym2); // false

Symbols can also be used as property keys in objects, providing a way to define non-enumerable properties:

const obj = {

[Symbol('prop1')]: 'value1',
[Symbol('prop2')]: 'value2',
};
console.log(Object.getOwnPropertySymbols(obj)); // [Symbol(prop1), Symbol(prop2)]

Additionally, symbols can be used as keys in ES6 Map and Set objects:

const map = new Map();

const key = Symbol('key');
map.set(key, 'value');
console.log(map.get(key)); // value
const set = new Set();
set.add(key);
console.log(set.has(key)); // true

As symbols are unique, they can be used to define well-known symbols, which are predefined symbols that exist as properties or methods on built-in objects. Well-known symbols follow the Symbol Symbol pattern. For example, the Symbol.iterator symbol is used to define the default iterator for an object:

const obj = {

[Symbol.iterator]() {
let index = -1;
const data = [1, 2, 3];
return {
next() {
index++;
return {
value: data[index],
done: index >= data.length,
};
},
};
},
};
for (const value of obj) {
console.log(value);
}

This example demonstrates how a symbol can be used to define custom iteration behavior for an object.

Unique Symbols

Unique symbols are a feature introduced in TypeScript 2.7 that allow you to create symbols that are guaranteed to be unique. This can be useful in scenarios where you need to create a unique identifier for a specific purpose.

Unique symbols are created using the Symbol() function. When called with an optional description, it returns a new unique symbol. The description is ignored for the purposes of uniqueness.

Here’s an example of how to create a unique symbol:

const mySymbol = Symbol();

Since unique symbols are guaranteed to be unique, they can be used as property keys in objects and symbols. Here’s an example:

const myObject = {

[mySymbol]: 'Hello, world!'
};
console.log(myObject[mySymbol]); // Output: Hello, world!

Unique symbols are typically used to create optional method or property names in objects. They provide a way to create unique identifiers without the risk of collision with other property names.

Unique symbols also have a number of built-in properties and methods that allow you to interact with them. For example, you can use the Symbol.keyFor() method to retrieve the key for a given symbol. Here’s an example:

const mySymbol = Symbol('mySymbol');

const key = Symbol.keyFor(mySymbol);
console.log(key); // Output: undefined

In this example, the Symbol.keyFor() method returns undefined because the symbol was created without a global registry.

Overall, unique symbols are a powerful feature in TypeScript that allow you to create unique identifiers for specific purposes. They provide a way to avoid collisions with other property names and can be useful in a wide range of scenarios.

Symbol Registry

The symbol registry is a globally accessible registry for symbols in TypeScript. It allows you to keep track of and access symbols by using unique keys.

Creating a Symbol

To create a symbol, you can use the Symbol() function, which returns a new unique symbol each time it is called:

const mySymbol = Symbol();

console.log(typeof mySymbol); // "symbol"

Registering a Symbol

To register a symbol in the symbol registry, you can use the Symbol.for() function. If the symbol is already registered, it will return the existing symbol, otherwise it will create and return a new one:

const mySymbol = Symbol.for('mySymbol');

console.log(mySymbol === Symbol.for('mySymbol')); // true

Accessing a Symbol

To access a symbol from the symbol registry, you can use the Symbol.keyFor() function. If the symbol is registered, it will return the key used to register it, otherwise it will return undefined:

const mySymbol = Symbol.for('mySymbol');

console.log(Symbol.keyFor(mySymbol)); // "mySymbol"

Listing all Registered Symbols

You can list all registered symbols using the Symbol.keyFor(Symbol.iterator) function:

const symbols = Object.getOwnPropertySymbols(globalThis);

const registeredSymbols = symbols.filter(symbol => Symbol.keyFor(symbol) !== undefined);
console.log(registeredSymbols);

Conclusion

The symbol registry provides a way to keep track of and access symbols globally. By using unique keys, it ensures that symbols can be easily identified and accessed throughout your TypeScript codebase.

Symbol Properties

A symbol is a unique and immutable data type that is often used as a property key in objects. In TypeScript, you can define symbol properties using the Symbol primitive.

Symbol properties have several key features:

Unique Identifier

Each symbol created using the Symbol function is guaranteed to be unique. This means that no two symbols will be equal, even if they have the same description.

Immutable

Symbol properties are immutable, meaning that their value cannot be changed once they are created. This makes symbols ideal for use as property keys that need to remain constant.

Privacy

Symbol properties are not exposed in for...in loops or when using the Object.keys() or Object.getOwnPropertyNames() methods. This allows you to define private or internal properties that are not enumerable.

Usage

To create a symbol property, you can use the Symbol() function:

const mySymbol = Symbol();

You can also provide an optional description that can be used for debugging purposes:

const mySymbol = Symbol('mySymbol');

Symbol properties can be used as property keys in objects:

const obj = {

[mySymbol]: 'value'
};

You can access the value of a symbol property using brackets or the dot notation:

console.log(obj[mySymbol]); // Output: 'value'

Or:

console.log(obj.mySymbol); // Output: 'value'

Note that using the dot notation will not work if the symbol property is not enumerable.

Symbol For

In addition to creating symbols using the Symbol() function, you can also create symbols using the Symbol.for() method. This method searches for an existing symbol with the given key and returns it if found, or creates a new symbol if it does not exist:

const mySymbol = Symbol.for('mySymbol');

You can then use the created symbol as a property key:

const obj = {

[mySymbol]: 'value'
};

The Symbol.for() method allows you to create symbols that can be shared across different parts of your codebase, ensuring that they are always the same symbol.

Symbol properties are a powerful and flexible feature in TypeScript that allow you to create unique and immutable property keys. They provide privacy and can be used to define private or internal properties that are not enumerable. Symbol properties are widely used in libraries and frameworks to define internal properties and prevent naming collisions.

Using Symbols as Object Keys

In TypeScript, symbols can be used as object keys, allowing us to create unique identifiers for properties and methods. This can help prevent name collisions and add more clarity to our code.

Creating and Using Symbols

To create a symbol, we use the Symbol() function. Each call to this function returns a new, unique symbol. We can assign the symbol to a variable for later use:

const mySymbol = Symbol();

We can then use this symbol as a key when creating an object:

const myObj = {

[mySymbol]: 'value'
};

Accessing the value associated with the symbol key is done by using the symbol in the square brackets notation:

console.log(myObj[mySymbol]); // output: 'value'

Preventing Name Collisions

By using symbols as object keys, we can prevent name collisions when working with multiple libraries or frameworks. Since symbols are unique, they provide a simple and effective way to avoid conflicts between different codebases:

// Library 1

const lib1Symbol = Symbol();
const lib1Obj = {
[lib1Symbol]: 'value'
};
// Library 2
const lib2Symbol = Symbol();
const lib2Obj = {
[lib2Symbol]: 'value'
};

Clarity in Code

Using symbols as object keys can also improve the clarity of our code. Since symbols are not exposed during normal object iteration, they can act as markers for internal uses. This can make it easier to understand the intended purpose of a property or method:

const privateSymbol = Symbol('private');

const myObj = {
public: 'public value',
[privateSymbol]: 'private value',
};
for (const key in myObj) {
console.log(key); // output: 'public'
}
console.log(privateSymbol); // output: Symbol(private)
console.log(myObj[privateSymbol]); // output: 'private value'

Conclusion

Using symbols as object keys in TypeScript can provide a powerful way to create unique identifiers and avoid name collisions. By leveraging this feature, we can improve the clarity and maintainability of our code.

Symbol Iterator

In TypeScript, the Symbol.iterator is a well-known symbol used to define the default Iterator for objects. An Iterator is an object that provides a sequence of values.

When an object has a Symbol.iterator property, it means that it is iterable, which means it can be looped over using the for...of loop or using other methods that expect an Iterable object.

Add the Symbol.iterator Property to an Object

To create an iterable object, you need to add the Symbol.iterator property to an object. The value assigned to this property must be a function that returns an iterator.

Here’s an example:

“`typescript

let myObject = {

data: [‘A’, ‘B’, ‘C’],

[Symbol.iterator]() {

let index = 0;

let data = this.data;

return {

next() {

if (index < data.length)="">

return {

value: data[index++],

done: false

};

} else {

return {

value: undefined,

done: true

};

}

}

};

}

}

for (let item of myObject) {

console.log(item);

}

“`

In the above example, the myObject has the Symbol.iterator property defined as a function that returns an iterator. The iterator is an object with a next method which returns the next value in the sequence.

Using the Symbol.iterator Property

Once the Symbol.iterator property is added to an object, you can use it in various ways.

For…of Loop

The most common way to use an iterable object is with the for...of loop. This loop automatically calls the Symbol.iterator to get the iterator object and then loops over the values until the iterator is done.

“`typescript

for (let item of myObject) {

console.log(item);

}

“`

Array.from

You can also use the Array.from method to convert an iterable object into an array.

“`typescript

let array = Array.from(myObject);

console.log(array);

“`

Built-in Iterables

JavaScript provides several built-in iterables, such as arrays, strings, maps, sets, etc. These objects have the Symbol.iterator property defined, so they can be used with the for...of loop or other methods that expect an iterable object.

Arrays

“`typescript

let letters = [‘A’, ‘B’, ‘C’];

for (let letter of letters) {

console.log(letter);

}

“`

Strings

“`typescript

let word = ‘Hello’;

for (let letter of word) {

console.log(letter);

}

“`

Maps

“`typescript

let myMap = new Map();

myMap.set(‘a’, 1);

myMap.set(‘b’, 2);

myMap.set(‘c’, 3);

for (let [key, value] of myMap) {

console.log(key, value);

}

“`

Sets

“`typescript

let mySet = new Set();

mySet.add(‘A’);

mySet.add(‘B’);

mySet.add(‘C’);

for (let item of mySet) {

console.log(item);

}

“`

Conclusion

The Symbol.iterator is a powerful feature in TypeScript that allows you to define custom iterators for your objects. By adding the Symbol.iterator property to your objects, you can make them iterable, providing a sequence of values that can be looped over using the for...of loop or other methods that expect an iterable object.

Symbol.toStringTag

The Symbol.toStringTag is a built-in Symbol in TypeScript that determines the value returned by the Object.prototype.toString() method. This symbol allows an object to provide a custom string representation for its tag when it is converted to a string.

By default, when Object.prototype.toString() is called on an object, it returns a generic string representation in the format "[object Object]". However, by defining a custom Symbol.toStringTag property on an object, you can change the tag that is displayed.

To define a custom Symbol.toStringTag for an object, you can use the following syntax:

// Create a new class

class MyClass {
// Define the Symbol.toStringTag property
get [Symbol.toStringTag]() {
return "CustomTag";
}
}
// Create a new instance of MyClass
const myObject = new MyClass();
// Call the toString() method on myObject
console.log(myObject.toString()); // Output: "[object CustomTag]"

In the above example, the MyClass class defines a custom Symbol.toStringTag property that returns the string "CustomTag". When the toString() method is called on an instance of MyClass, the output will be "[object CustomTag]".

The Symbol.toStringTag property is useful in scenarios where you want to provide more meaningful information about the type of an object when it is converted to a string. It allows for better readability and debugging.

It is important to note that the Symbol.toStringTag property does not affect the behavior of an object itself. It only provides a custom tag when the toString() method is called on the object.

Global Symbols

Introduction

In TypeScript, global symbols are special characters or signs that have a global meaning and are used in various contexts throughout the language.

Common Global Symbols

Here are some common global symbols used in TypeScript:

• $ (dollar sign): Used as a prefix for variable names, often in the context of jQuery.
• _ (underscore): Used as a prefix for private members in classes.
• ! (exclamation mark): Used as a postfix for non-null assertions.
• ? (question mark): Used to denote optional properties or parameters.
• # (hash sign): Used as a prefix for private class fields.

Examples

Here are some examples of global symbols in TypeScript:

• var $element = $('#myElement');
• class MyClass {

  private _myProperty: number;

  }

• function myFunction(someValue: string | null) {

  console.log(someValue!);

  }

• interface MyInterface {

  optionalProperty?: string;

  }

• class MyPrivateClass {

  #privateField: number;

  }

Conclusion

Understanding global symbols in TypeScript is important for efficiently reading and writing code. By knowing their meaning and usage, you can better navigate and comprehend TypeScript code written by others.

Symbol Polyfill

In JavaScript, the Symbol data type was introduced in ECMAScript 2015 as a way to create unique identifiers. Symbols are often used as property keys in objects to avoid name collisions.

While modern browsers and environments support Symbols, if you need to run your TypeScript code in older environments that don’t have native Symbol support, you can use a Symbol polyfill.

What is a polyfill?

A polyfill is a piece of code that provides the functionality of a newer JavaScript feature in older environments that don’t natively support it. It essentially “fills in” the missing functionality so that your code can run without throwing errors.

Symbol polyfills

There are several Symbol polyfills available that can be used to provide Symbol support in older environments. These polyfills typically provide a global Symbol object and related functions for creating and using symbols.

Some popular Symbol polyfills include:

• es6-symbol
• vidom
• rxjs

To use a Symbol polyfill, you typically include the polyfill script in your HTML file before your TypeScript code. Once the polyfill is loaded, you can use Symbols just like you would in a modern environment.

Conclusion

If you need to run your TypeScript code in older environments without native Symbol support, Symbol polyfills provide a way to “fill in” the missing functionality. By including a Symbol polyfill in your code, you can use Symbols just like you would in a modern environment.

FAQ:

What is a symbol in TypeScript?

In TypeScript, a symbol is a data type that represents a unique identifier. It is useful when you want to create properties or methods that are not accessible in a normal way.

How can I create a symbol in TypeScript?

To create a symbol in TypeScript, you can use the `Symbol` function. For example: `const mySymbol = Symbol(“mySymbol”);`. The argument passed to the `Symbol` function is optional and is only used for debugging purposes.

Can symbols be compared with each other?

No, symbols cannot be compared with each other using the `==` or `===` operators. Each symbol created using the `Symbol` function is unique and cannot be equal to any other symbol.

Are symbols automatically converted to strings?

No, symbols are not automatically converted to strings. If you try to concatenate a symbol with a string using the `+` operator, you will get a TypeError. If you want to convert a symbol to a string, you can use the `toString()` method of the symbol object.

Can symbols be used as object keys in TypeScript?

Yes, symbols can be used as object keys in TypeScript. The key type for a symbol property is `symbol`. When you create an object with symbol properties, you can access them using the bracket notation, like this: `myObject[mySymbol]`.

Can symbols be used as class or interface property names in TypeScript?

Yes, symbols can be used as property names in classes and interfaces in TypeScript. When defining a class or interface, you can use symbols as property names just like any other valid property name, for example: `class MyClass { [mySymbol]: string; }`.