From b33423bcbe544d2045da60cfa4216da5e361cc7c Mon Sep 17 00:00:00 2001 From: Sami Vaarala Date: Thu, 29 Sep 2016 07:19:48 +0300 Subject: [PATCH] 2.x migration notes for Symbols --- doc/release-notes-v2-0.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/doc/release-notes-v2-0.rst b/doc/release-notes-v2-0.rst index 2aaed3a1..9ac1be04 100644 --- a/doc/release-notes-v2-0.rst +++ b/doc/release-notes-v2-0.rst @@ -1022,6 +1022,36 @@ To upgrade: * Check application code for enumeration assumptions. +Symbol support related changes +------------------------------ + +Small changes related to adding symbol support: + +* Symbols are represented as strings with an invalid UTF-8 representation (like + internal keys in Duktape 1.x), and they behave like strings in the C API just + like internal keys did in Duktape 1.x. For example, ``duk_is_string()`` is + true for symbols. + +* Symbol support is currently **experimental**. The core semantics have been + implemented but it's likely some of the internal details will change in future + releases. The C API may also need changes (for example to the typing model) + in future releases; in its current form symbols behave just like internal + strings in the C API. + +* Being experimental, the ``Symbol`` built-in is disabled by default; enable via + config option ``DUK_USE_SYMBOL_BUILTIN``. Symbols can be created from C code + even when the ``Symbol`` built-in is disabled, and symbol semantics (like + ``typeof`` and coercion behavior) are currently enabled. + +* Internal properties are now called "hidden symbols" and adopt some ES6 Symbol + behaviors, e.g. ``typeof internalKey === 'symbol`` and ``"" + internalKey`` + is now a TypeError. Internal keys are different from normal ES6 Symbols in + that they can't be enumerated from Ecmascript code even with + ``Object.getOwnPropertySymbols()``. + +* The ``DUK_ENUM_INCLUDE_INTERNAL`` C API flag has been renamed + ``DUK_ENUM_INCLUDE_HIDDEN``. + Other incompatible changes --------------------------