ES6 Symbol

1. Overview

ES5 object property names are 字符串 which can easily cause conflicts 属性名 names. F or example, if you use an object that someone else provides, but want to add a new method (mixin pattern) to that object, the name of the new method might conflict with the existing method. I f only there were a mechanism to ensure that the names of each property were unique, thus fundamentally preventing conflicts between property names. That's why ES6 introduced Symbol.

ES6 introduces a new raw data Symbol that represents a unique value. It is the seventh 第七 the JavaScript language, and the first six are: undefined, null, Boolean, String, Number, Object.

Symbol value is Symbol 函数 function. T his means that the property name of an object can now be of two types, one is a string that was originally available and the other is a new Symbol type. Any property name that belongs to the Symbol type is unique and can be guaranteed not to conflict with other property names.

let s = Symbol();
typeof s
// "symbol"

In the code above, the variable s is a unique value. The result of the typeof operator, which indicates that the variable s is a Symbol data type, not other types such as strings.

Note that the symbol function cannot use the new command before, otherwise an error will be reported. T his is because the resulting Symbol is a value of the original type, not an object. T hat is, properties cannot be added because the Symbol value is not an object. Basically, it is a string-like data type.

The Symbol function can accept a string as an argument to represent a description of the Symbol instance, primarily to make it easier to distinguish when displayed in the console or converted to a string.

let s1 = Symbol('foo');
let s2 = Symbol('bar');
s1 // Symbol(foo)
s2 // Symbol(bar)
s1.toString() // "Symbol(foo)"
s2.toString() // "Symbol(bar)"

In the code above, s1 and s2 are two Symbol values. W ithout parameters, their output in the console is Symbol(), which is not conducive to differentiation. With parameters, they are described, and the output can tell which value it is.

If Symbol's argument is an object, the object's toString method is called, converted into a string, and then a Symbol value is generated.

const obj = {
  toString() {
    return 'abc';
  }
};
const sym = Symbol(obj);
sym // Symbol(abc)

Note that the parameters of the Symbol function simply represent a description of the current Symbol value, so the return value of the Symbol function of the same parameter is not equal.

// 没有参数的情况
let s1 = Symbol();
let s2 = Symbol();
s1 === s2 // false
// 有参数的情况
let s1 = Symbol('foo');
let s2 = Symbol('foo');
s1 === s2 // false

In the code above, s1 and s2 are both return values for symbol functions, and the parameters are the same, but they are not equal.

Symbol values cannot be performed with other types of values and are reported as errors.

let sym = Symbol('My symbol');
"your symbol is " + sym
// TypeError: can't convert symbol to string
`your symbol is ${sym}`
// TypeError: can't convert symbol to string

However, the Symbol value can be explicitly converted to a string.

let sym = Symbol('My symbol');
String(sym) // 'Symbol(My symbol)'
sym.toString() // 'Symbol(My symbol)'

In addition, symbol values can be converted to Boolean values, but not values.

let sym = Symbol();
Boolean(sym) // true
!sym  // false
if (sym) {
  // ...
}
Number(sym) // TypeError
sym + 2 // TypeError

2. Symbol.prototype.description

When you create Symbol, you can add a description.

const sym = Symbol('foo');

In the code above, the description of sym is the string foo.

However, reading this description requires explicitly converting Symbol into a string, which is the following method of writing.

const sym = Symbol('foo');
String(sym) // "Symbol(foo)"
sym.toString() // "Symbol(foo)"

The above usage is not very convenient. ES2019 provides an instance property description that returns a description of Symbol directly.

const sym = Symbol('foo');
sym.description // "foo"

3. Symbol as the property name

Because each Symbol value is not equal, this means that Symbol 值 be used as an 标识符 for the object's property name, guaranteeing that no properties with the same name will appear. This is useful in situations in which an object consists of multiple modules and prevents a key from being accidentally overwritten or overwritten.

let mySymbol = Symbol();
// 第一种写法
let a = {};
a[mySymbol] = 'Hello!';
// 第二种写法
let a = {
  [mySymbol]: 'Hello!'
};
// 第三种写法
let a = {};
Object.defineProperty(a, mySymbol, { value: 'Hello!' });
// 以上写法都得到同样结果
a[mySymbol] // "Hello!"

The above code specifies the object's property name as a Symbol value through the square bracket structure and Object.defineProperty.

Note that the Symbol value cannot be used with a point operator when it is an object property name.

const mySymbol = Symbol();
const a = {};
a.mySymbol = 'Hello!';
a[mySymbol] // undefined
a['mySymbol'] // "Hello!"

In the above code, because the point operator is always followed by a string, the value that mySymbol refers to as an identification name is not read, resulting in a property name that is actually a string, not a Symbol value.

Similarly, within an object, when a property is defined with a Symbol value, the Symbol value must be placed in square brackets.

let s = Symbol();
let obj = {
  [s]: function (arg) { ... }
};
obj[s](123);

In the above code, if s is not placed in square brackets, the key name of the property is string s, not the Symbol value represented by s.

With enhanced object writing, the obj objects in the above code can be written more concisely.

let obj = {
  [s](arg) { ... }
};

Symbol types can also be used to define a set of constants to ensure that the values of that set of constants are not equal.

const log = {};
log.levels = {
  DEBUG: Symbol('debug'),
  INFO: Symbol('info'),
  WARN: Symbol('warn')
};
console.log(log.levels.DEBUG, 'debug message');
console.log(log.levels.INFO, 'info message');

Here's another example.

const COLOR_RED    = Symbol();
const COLOR_GREEN  = Symbol();
function getComplement(color) {
  switch (color) {
    case COLOR_RED:
      return COLOR_GREEN;
    case COLOR_GREEN:
      return COLOR_RED;
    default:
      throw new Error('Undefined color');
    }
}

The biggest benefit of using symbol values for constants is that no other value can have the same value, so you can guarantee that the switch statement above will work as designed.

It is also important to note that Symbol value is the name of the 属性名 the property is still a 公开属性 not a private property.

4. Example: Eliminates magic strings

魔术字符串 is a specific string or value that appears multiple 强耦合 is strongly coupled to the code. Good-style code should try to eliminate magic strings and replace them with variables with clear meanings.

function getArea(shape, options) {
  let area = 0;
  switch (shape) {
    case 'Triangle': // 魔术字符串
      area = .5 * options.width * options.height;
      break;
    /* ... more code ... */
  }
  return area;
}
getArea('Triangle', { width: 100, height: 100 }); // 魔术字符串

In the code above, the string Triangle is a magic string. It appears several times and forms a “强耦合” is not conducive to future modification and maintenance.

The common way to eliminate magic strings is to write it as a variable.

const shapeType = {
  triangle: 'Triangle'
};
function getArea(shape, options) {
  let area = 0;
  switch (shape) {
    case shapeType.triangle:
      area = .5 * options.width * options.height;
      break;
  }
  return area;
}
getArea(shapeType.triangle, { width: 100, height: 100 });

In the code above, we write Triangle as the triangle property of the shapeType object, which eliminates strong coupling.

If you analyze it carefully, it doesn't matter which value shapeType.triangle is equal to, as long as you make sure that it doesn't conflict with the values of other shapeType properties. Therefore, it's a good place to switch to symbol values.

const shapeType = {
  triangle: Symbol()
};

In the above code, the value of shapeType.triangle is set to a Symbol, which need not be modified anywhere else.

5. Traversal of the property name

Symbol a property name, when traversing an object, the property does not appear in for... i n 、 for... In the loop, it will not be returned by Object.keys(), Object.getOwnPropertyNames(), JSON.stringify().

However, it is not a private property, and there is Object.getOwnPropertySymbols() gets all symbol property names for the specified object. The method returns an array of symbol values that are all used as property names by the current object.

const obj = {};
let a = Symbol('a');
let b = Symbol('b');
obj[a] = 'Hello';
obj[b] = 'World';
const objectSymbols = Object.getOwnPropertySymbols(obj);
objectSymbols
// [Symbol(a), Symbol(b)]

The above code is an example of the Object.getOwnPropertySymbols() method, which gets all symbol property names.

Here's another example, object.getOwnPropertySymbols() method with for... Examples of in loops, Object.getOwnPropertyNames methods for comparison.

const obj = {};
const foo = Symbol('foo');
obj[foo] = 'bar';
for (let i in obj) {
  console.log(i); // 无输出
}
Object.getOwnPropertyNames(obj) // []
Object.getOwnPropertySymbols(obj) // [Symbol(foo)]

In the code above, use for... Between the in loop and the Object.getOwnPropertyNames() method do not get the Symbol key name and require the Object.getOwnPropertySymbols() method.

Another new API, the Reflect.ownKeys() method, can return key names of all types, including regular key names and Symbol key names.

let obj = {
  [Symbol('my_key')]: 1,
  enum: 2,
  nonEnum: 3
};
Reflect.ownKeys(obj)
//  ["enum", "nonEnum", Symbol(my_key)]

Because the Symbol value is the key name, it is not traversed by the regular method. We can use this feature to define non-private methods for objects that we want to use only internally.

let size = Symbol('size');
class Collection {
  constructor() {
    this[size] = 0;
  }
  add(item) {
    this[this[size]] = item;
    this[size]++;
  }
  static sizeOf(instance) {
    return instance[size];
  }
}
let x = new Collection();
Collection.sizeOf(x) // 0
x.add('foo');
Collection.sizeOf(x) // 1
Object.keys(x) // ['0']
Object.getOwnPropertyNames(x) // ['0']
Object.getOwnPropertySymbols(x) // [Symbol(size)]

In the above code, the size property of object x is a Symbol value, so object.keys(x), Object.getOwnPropertyNames(x) can't get it. This creates the effect of a non-private internal approach.

6. Symbol.for()，Symbol.keyFor()

Sometimes we want to re-use the same Symbol value, Symbol.for() method can do. I t accepts a string as an argument, and then searches for symbol values with that parameter as its name. If so, the Symbol value is returned, otherwise a new Symbol value with the string's name is created and registered globally.

let s1 = Symbol.for('foo');
let s2 = Symbol.for('foo');
s1 === s2 // true

In the above code, s1 and s2 are Both Symbol values, but they are both generated by the Symbol.for method of the same parameter, so they are actually the same value.

Symbol.for() Symbol() generate new Symbols. T he difference is that the former is registered for search in a global environment and the latter is not. S ymbol.for() does not return a value of a new Symbol type with each call, but checks whether a given key already exists and creates a new value if it does not exist. For example, if you call Symbol.for ("cat") 30 times, you will return the same Symbol value each time, but if you call Symbol ("cat") 30 times, you will return 30 different Symbol values.

Symbol.for("bar") === Symbol.for("bar")
// true
Symbol("bar") === Symbol("bar")
// false

In the above code, since symbol() does not have a registration mechanism, a different value is returned for each call.

The Symbol.keyFor() method returns the key of a registered Symbol type value.

let s1 = Symbol.for("foo");
Symbol.keyFor(s1) // "foo"
let s2 = Symbol("foo");
Symbol.keyFor(s2) // undefined

In the code above, the variable s2 belongs to an unregistered Symbol value, so undefined is returned.

Note that symbol.for() is the name registered for the Symbol value and is a global environment, whether or not it is running in the global environment.

function foo() {
  return Symbol.for('bar');
}
const x = foo();
const y = Symbol.for('bar');
console.log(x === y); // true

In the above code, Symbol.for ('bar') runs inside the function, but the resulting Symbol value is registered in the global environment. Therefore, the second run of Symbol.for ('bar') can get this Symbol value.

This global registration feature of Symbol.for() can be taken from the same value in different iframe or service workers.

iframe = document.createElement('iframe');
iframe.src = String(window.location);
document.body.appendChild(iframe);
iframe.contentWindow.Symbol.for('foo') === Symbol.for('foo')
// true

In the code above, the Symbol value generated by the iframe window is available on the main page.

7. Example: Singleton mode for modules

Singleton mode refers to calling a class that returns the same instance at any time.

For Node, a module file can be thought of as a class. How to ensure that every time this module file is executed, the same instance is returned?

It's easy to think that you can put an instance on top-level object global.

// mod.js
function A() {
  this.foo = 'hello';
}
if (!global._foo) {
  global._foo = new A();
}
module.exports = global._foo;

Then, load the mod .js.

const a = require('./mod.js');
console.log(a.foo);

In the code above, variable a loads the same instance of A at any time.

However, there is a problem with global variables global._foo can be written and any file can be modified.

global._foo = { foo: 'world' };
const a = require('./mod.js');
console.log(a.foo);

The code above distorts the scripts .js the mods and mods.

To prevent this from happening, we can use Symbol.

// mod.js
const FOO_KEY = Symbol.for('foo');
function A() {
  this.foo = 'hello';
}
if (!global[FOO_KEY]) {
  global[FOO_KEY] = new A();
}
module.exports = global[FOO_KEY];

In the code above, it is guaranteed that global FOO_KEY will not be inadvertently overwritten, but can still be rewritten.

global[Symbol.for('foo')] = { foo: 'world' };
const a = require('./mod.js');

If the key name is generated using the Symbol method, the value cannot be referenced externally and, of course, cannot be overwrite.

// mod.js
const FOO_KEY = Symbol('foo');
// 后面代码相同 ……

The above code will cause no other script to FOO_KEY. B ut there is also the problem that if you execute this script multiple times, the FOO_KEY is different. Although Node caches the execution results of the script, in general, the same script is not executed more than once, but the user can manually clear the cache, so it is not absolutely reliable.

8. The built-in Symbol value

In addition to defining the Symbol values you use, ES6 11 Symbol values that point to methods used inside the language.

Symbol.hasInstance

The Symbol.hasInstance of the object, pointing to an internal method. T his method is called when other objects use the instanceof operator to determine if it is an instance of the object. For example, within the language, foo Instanceof Foo is actually called Foo Symbol.hasInstance.

class MyClass {
  [Symbol.hasInstance](foo) {
    return foo instanceof Array;
  }
}
[1, 2, 3] instanceof new MyClass() // true

In the code above, MyClass is a class, and new MyClass() returns an instance. The Symbol.hasInstance method for the instance is automatically called when the instanceof operation is performed to determine whether the operator on the left is an instance of Array.

Here's another example.

class Even {
  static [Symbol.hasInstance](obj) {
    return Number(obj) % 2 === 0;
  }
}
// 等同于
const Even = {
  [Symbol.hasInstance](obj) {
    return Number(obj) % 2 === 0;
  }
};
1 instanceof Even // false
2 instanceof Even // true
12345 instanceof Even // false

Symbol.isConcatSpreadable

The Symbol.isConcatSpreadable is equal to a Boolean value, indicating whether the object can be expanded when used for Array.prototype.concat() 布尔值

let arr1 = ['c', 'd'];
['a', 'b'].concat(arr1, 'e') // ['a', 'b', 'c', 'd', 'e']
arr1[Symbol.isConcatSpreadable] // undefined
let arr2 = ['c', 'd'];
arr2[Symbol.isConcatSpreadable] = false;
['a', 'b'].concat(arr2, 'e') // ['a', 'b', ['c','d'], 'e']

The code above states that the default behavior of the array is expandable, and Symbol.isConcatSpreadable is equal to undefined by default. This property also has an expanded effect when it is equal to true.

Array-like objects do the opposite and do not expand by default. Its Symbol.isConcatSpreadable property is set to true before it can be expanded.

let obj = {length: 2, 0: 'c', 1: 'd'};
['a', 'b'].concat(obj, 'e') // ['a', 'b', obj, 'e']
obj[Symbol.isConcatSpreadable] = true;
['a', 'b'].concat(obj, 'e') // ['a', 'b', 'c', 'd', 'e']

The Symbol.isConSpreadcatable property can also be defined in a class.

class A1 extends Array {
  constructor(args) {
    super(args);
    this[Symbol.isConcatSpreadable] = true;
  }
}
class A2 extends Array {
  constructor(args) {
    super(args);
  }
  get [Symbol.isConcatSpreadable] () {
    return false;
  }
}
let a1 = new A1();
a1[0] = 3;
a1[1] = 4;
let a2 = new A2();
a2[0] = 5;
a2[1] = 6;
[1, 2].concat(a1).concat(a2)
// [1, 2, 3, 4, [5, 6]]

In the above code, class A1 is expandable, class A2 is not expandable, so there are different results when using concat.

Note that symbol.isConcatSpreadable's position difference, A1 is defined on the instance, A2 is defined on the class itself, and the effect is the same.

Symbol.species

The Symbol.species the object, pointing to 构造函数 This property is used when creating derived objects.

class MyArray extends Array {
}
const a = new MyArray(1, 2, 3);
const b = a.map(x => x);
const c = a.filter(x => x > 1);
b instanceof MyArray // true
c instanceof MyArray // true

In the above code, the child class MyArray inherits the parent class Array, a is an instance of MyArray, and b and c are derivative objects of a. You might think that both b and c are generated by calling array methods, so they should be arrays (instances of Array), but they are actually instances of MyArray.

The Symbol.species property is provided to solve this problem. Now we can set the Symbol.speciess property for MyArray.

class MyArray extends Array {
  static get [Symbol.species]() { return Array; }
}

In the above code, because the Symbol.species property is defined, the function returned by the derived object is used as a constructor when the derived object is created. T his example also shows that the Symbol.species property is defined using a get value extractor. The default Symbol.species property is equivalent to the following writing.

static get [Symbol.species]() {
  return this;
}

Now, let's look at the previous example.

class MyArray extends Array {
  static get [Symbol.species]() { return Array; }
}
const a = new MyArray();
const b = a.map(x => x);
b instanceof MyArray // false
b instanceof Array // true

In the code above, the derived object generated by a.map (x sgt; x) is not an instance of MyArray, but directly an instance of Array.

Let's look at another example.

class T1 extends Promise {
}
class T2 extends Promise {
  static get [Symbol.species]() {
    return Promise;
  }
}
new T1(r => r()).then(v => v) instanceof T1 // true
new T2(r => r()).then(v => v) instanceof T2 // false

In the code above, T2 defines the Symbol.species property, T1 does not. The result is that when a derived object is created (the then method), T1 calls its own construction method, and T2 calls Promise's construction method.

In summary, symbol.speciess is designed to call the constructor specified by the property when the instance object needs to call its own constructor again while it is running. Its main purpose is that some class libraries are modified on the basis of the base class, so when the sub-class uses the inherited method, the author may want to return an instance of the base class instead of an instance of the sub-class.

Symbol.match

The Symbol.match of the object, pointing to 函数 When str.match(myObject) it is called and the return value of the method is returned.

String.prototype.match(regexp)
// 等同于
regexp[Symbol.match](this)
class MyMatcher {
  [Symbol.match](string) {
    return 'hello world'.indexOf(string);
  }
}
'e'.match(new MyMatcher()) // 1

Symbol.replace

The Symbol.replace of an object points to 方法 that returns a return value when it is called by the String.prototype.replace method.

String.prototype.replace(searchValue, replaceValue)
// 等同于
searchValue[Symbol.replace](this, replaceValue)

Here's an example.

const x = {};
x[Symbol.replace] = (...s) => console.log(s);
'Hello'.replace(x, 'World') // ["Hello", "World"]

The Symbol.replace method receives two arguments, the first being the object that the replace method is working on, hello in the example above, and the second argument being the replaced value, and the world in the example above.

Symbol.search

The Symbol.search of an object that points 方法 a method that returns a return value when it is called by the String.prototype.search method.

String.prototype.search(regexp)
// 等同于
regexp[Symbol.search](this)
class MySearch {
  constructor(value) {
    this.value = value;
  }
  [Symbol.search](string) {
    return string.indexOf(this.value);
  }
}
'foobar'.search(new MySearch('foo')) // 0

Symbol.split

The Symbol.split of an object that points 方法 method that returns a return value when it is called by the String.prototype.split method.

String.prototype.split(separator, limit)
// 等同于
separator[Symbol.split](this, limit)

Here's an example.

class MySplitter {
  constructor(value) {
    this.value = value;
  }
  [Symbol.split](string) {
    let index = string.indexOf(this.value);
    if (index === -1) {
      return string;
    }
    return [
      string.substr(0, index),
      string.substr(index + this.value.length)
    ];
  }
}
'foobar'.split(new MySplitter('foo'))
// ['', 'bar']
'foobar'.split(new MySplitter('bar'))
// ['foo', '']
'foobar'.split(new MySplitter('baz'))
// 'foobar'

The above method redefines the behavior of the string object's split method using the Symbol.split method.

Symbol.iterator

The Symbol.iterator the object, pointing to the 默认遍历器 method.

const myIterable = {};
myIterable[Symbol.iterator] = function* () {
  yield 1;
  yield 2;
  yield 3;
};
[...myIterable] // [1, 2, 3]

Object for...of you loop, the Symbol.iterator returning the object's default traverser, see Iterator and for... A chapter on the loop.

class Collection {
  *[Symbol.iterator]() {
    let i = 0;
    while(this[i] !== undefined) {
      yield this[i];
      ++i;
    }
  }
}
let myCollection = new Collection();
myCollection[0] = 1;
myCollection[1] = 2;
for(let value of myCollection) {
  console.log(value);
}
// 1
// 2

Symbol.toPrimitive

The Symbol.toPrimitive of the object, pointing to 方法 When the object is converted to a value of the original type, the method is called to return the original type value for the object.

When Symbol.toPrimitive is called, it accepts a string argument that represents the pattern of the current operation, which has three modes.

Number: This occasion needs to be converted to a value
String: This occasion needs to be turned into a string
Default: This occasion can be converted to a value or to a string

let obj = {
  [Symbol.toPrimitive](hint) {
    switch (hint) {
      case 'number':
        return 123;
      case 'string':
        return 'str';
      case 'default':
        return 'default';
      default:
        throw new Error();
     }
   }
};
2 * obj // 246
3 + obj // '3default'
obj == 'default' // true
String(obj) // 'str'

Symbol.toStringTag

The Symbol.toStringTag of the object, pointing to 方法 W hen the Object.prototype.toString if the property exists, its return value appears in the string returned by the toString method, indicating the type of object. That is, this property can be used to customize the string that follows object in the object Object or object Array.

// 例一
({[Symbol.toStringTag]: 'Foo'}.toString())
// "[object Foo]"
// 例二
class Collection {
  get [Symbol.toStringTag]() {
    return 'xxx';
  }
}
let x = new Collection();
Object.prototype.toString.call(x) // "[object xxx]"

The Symbol.toStringTag property values for the new built-in objects for ES6 are as follows.

JSON[Symbol.toStringTag] ：'JSON'
Math[Symbol.toStringTag] ：'Math'
Module Object M (Symbol.toStringTag) : 'Module'
ArrayBuffer.prototype[Symbol.toStringTag] ：'ArrayBuffer'
DataView.prototype[Symbol.toStringTag] ：'DataView'
Map.prototype[Symbol.toStringTag] ：'Map'
Promise.prototype[Symbol.toStringTag] ：'Promise'
Set.prototype[Symbol.toStringTag] ：'Set'
%TypedArray.prototype (Symbol.toStringTag) : 'Uint8Array' and so on
WeakMap.prototype[Symbol.toStringTag] ：'WeakMap'
WeakSet.prototype[Symbol.toStringTag] ：'WeakSet'
%MapIteratorPrototype%[Symbol.toStringTag] ：'Map Iterator'
%SetIteratorPrototype%[Symbol.toStringTag] ：'Set Iterator'
%StringIteratorPrototype%[Symbol.toStringTag] ：'String Iterator'
Symbol.prototype[Symbol.toStringTag] ：'Symbol'
Generator.prototype[Symbol.toStringTag] ：'Generator'
GeneratorFunction.prototype[Symbol.toStringTag] ：'GeneratorFunction'

Symbol.unscopables

The Symbol.unscopables the object, pointing to 对象 The object specifies which with by the with environment when using the with keyword.

Array.prototype[Symbol.unscopables]
// {
//   copyWithin: true,
//   entries: true,
//   fill: true,
//   find: true,
//   findIndex: true,
//   includes: true,
//   keys: true
// }
Object.keys(Array.prototype[Symbol.unscopables])
// ['copyWithin', 'entries', 'fill', 'find', 'findIndex', 'includes', 'keys']

The code above states that the array has 7 properties that are excluded by the with command.

// 没有 unscopables 时
class MyClass {
  foo() { return 1; }
}
var foo = function () { return 2; };
with (MyClass.prototype) {
  foo(); // 1
}
// 有 unscopables 时
class MyClass {
  foo() { return 1; }
  get [Symbol.unscopables]() {
    return { foo: true };
  }
}
var foo = function () { return 2; };
with (MyClass.prototype) {
  foo(); // 2
}

The above code does not Symbol.unscopables i.e. the variable that foo will point to the outer scope.

Table of contents