sync-07-object-properties

Author: vplentinax

1-js/07-object-properties/01-property-descriptors/article.md

@@ -3,15 +3,15 @@
 
 As we know, objects can store properties.
 
-Till now, a property was a simple "key-value" pair to us. But an object property is actually a more flexible and powerful thing.
+Until now, a property was a simple "key-value" pair to us. But an object property is actually a more flexible and powerful thing.
 
 In this chapter we'll study additional configuration options, and in the next we'll see how to invisibly turn them into getter/setter functions.
 
 ## Property flags
 
 Object properties, besides a **`value`**, have three special attributes (so-called "flags"):
 
--**`writable`** -- if `true`, can be changed, otherwise it's read-only.
+-**`writable`** -- if `true`, the value can be changed, otherwise it's read-only.
 -**`enumerable`** -- if `true`, then listed in loops, otherwise not listed.
 -**`configurable`** -- if `true`, the property can be deleted and these attributes can be modified, otherwise not.
 
@@ -63,10 +63,10 @@ Object.defineProperty(obj, propertyName, descriptor)
 ```
 
 `obj`, `propertyName`
-: The object and property to work on.
+: The object and its property to apply the descriptor.
 
 `descriptor`
-: Property descriptor to apply.
+: Property descriptor object to apply.
 
 If the property exists, `defineProperty` updates its flags. Otherwise, it creates the property with the given value and flags; in that case, if a flag is not supplied, it is assumed `false`.
 
@@ -100,9 +100,9 @@ Compare it with "normally created" `user.name` above: now all flags are falsy. I
 
 Now let's see effects of the flags by example.
 
-## Read-only
+## Non-writable
 
-Let's make `user.name`read-only by changing `writable` flag:
+Let's make `user.name`non-writable (can't be reassigned) by changing `writable` flag:
 
 ```js run
 let user ={
@@ -116,36 +116,39 @@ Object.defineProperty(user, "name",{
 });
 
 *!*
-user.name="Pete"; // Error: Cannot assign to read only property 'name'...
+user.name="Pete"; // Error: Cannot assign to read only property 'name'
 */!*
 ```
 
 Now no one can change the name of our user, unless they apply their own `defineProperty` to override ours.
 
-Here's the same operation, but for the case when a property doesn't exist:
+```smart header="Errors appear only in strict mode"
+In the non-strict mode, no errors occur when writing to non-writable properties and such. But the operation still won't succeed. Flag-violating actions are just silently ignored in non-strict.
+```
+
+Here's the same example, but the property is created from scratch:
 
 ```js run
 let user ={};
 
 Object.defineProperty(user, "name",{
 *!*
- value:"Pete",
-// for new properties need to explicitly list what's true
+ value:"John",
+// for new properties we need to explicitly list what's true
  enumerable:true,
  configurable:true
 */!*
 });
 
-alert(user.name); //Pete
-user.name="Alice"; // Error
+alert(user.name); //John
+user.name="Pete"; // Error
 ```
 
-
 ## Non-enumerable
 
 Now let's add a custom `toString` to `user`.
 
-Normally, a built-in `toString` for objects is non-enumerable, it does not show up in `for..in`. But if we add `toString` of our own, then by default it shows up in `for..in`, like this:
+Normally, a built-in `toString` for objects is non-enumerable, it does not show up in `for..in`. But if we add a `toString` of our own, then by default it shows up in `for..in`, like this:
 
 ```js run
 let user ={
@@ -159,7 +162,7 @@ let user ={
 for (let key in user) alert(key); // name, toString
 ```
 
-If we don't like it, then we can set `enumerable:false`. Then it won't appear in `for..in` loop, just like the built-in one:
+If we don't like it, then we can set `enumerable:false`. Then it won't appear in a `for..in` loop, just like the built-in one:
 
 ```js run
 let user ={
@@ -191,9 +194,9 @@ alert(Object.keys(user)); // name
 
 The non-configurable flag (`configurable:false`) is sometimes preset for built-in objects and properties.
 
-A non-configurable property can not be deleted or altered with `defineProperty`.
+A non-configurable property can not be deleted.
 
-For instance, `Math.PI` is read-only, non-enumerable and non-configurable:
+For instance, `Math.PI` is non-writable, non-enumerable and non-configurable:
 
 ```js run
 let descriptor =Object.getOwnPropertyDescriptor(Math, 'PI');
@@ -216,7 +219,13 @@ Math.PI = 3; // Error
 // delete Math.PI won't work either
 ```
 
-Making a property non-configurable is a one-way road. We cannot change it back, because `defineProperty` doesn't work on non-configurable properties.
+Making a property non-configurable is a one-way road. We cannot change it back with `defineProperty`.
+
+To be precise, non-configurability imposes several restrictions on `defineProperty`:
+1. Can't change `configurable` flag.
+2. Can't change `enumerable` flag.
+3. Can't change `writable: false` to `true` (the other way round works).
+4. Can't change `get/set` for an accessor property (but can assign them if absent).
 
 Here we are making `user.name` a "forever sealed" constant:
 
@@ -234,13 +243,15 @@ Object.defineProperty(user, "name",{
 // all this won't work:
 // user.name = "Pete"
 // delete user.name
-// defineProperty(user, "name", ...)
+// defineProperty(user, "name", {value: "Pete" })
 Object.defineProperty(user, "name",{writable:true}); // Error
 */!*
 ```
 
-```smart header="Errors appear only in use strict"
-In the non-strict mode, no errors occur when writing to read-only properties and such. But the operation still won't succeed. Flag-violating actions are just silently ignored in non-strict.
+```smart header="\"Non-configurable\" doesn't mean \"non-writable\""
+Notable exception: a value of non-configurable, but writable property can be changed.
+
+The idea of `configurable: false` is to prevent changes to property flags and its deletion, not changes to its value.
 ```
 
 ## Object.defineProperties
@@ -298,13 +309,13 @@ Property descriptors work at the level of individual properties.
 There are also methods that limit access to the *whole* object:
 
 [Object.preventExtensions(obj)](mdn:js/Object/preventExtensions)
-: Forbids to add properties to the object.
+: Forbids the addition of new properties to the object.
 
 [Object.seal(obj)](mdn:js/Object/seal)
-: Forbids to add/remove properties, sets for all existing properties`configurable: false`.
+: Forbids adding/removing of properties. Sets `configurable: false`for all existing properties.
 
 [Object.freeze(obj)](mdn:js/Object/freeze)
-: Forbids to add/remove/change properties, sets for all existing properties`configurable: false, writable: false`.
+: Forbids adding/removing/changing of properties. Sets `configurable: false, writable: false` for all existing properties.
 
 And also there are tests for them:
 

1-js/07-object-properties/02-property-accessors/article.md

@@ -3,7 +3,7 @@
 
 There are two kinds of properties.
 
-The first kind is *data properties*. We already know how to work with them. Actually, all properties that we've been using till now were data properties.
+The first kind is *data properties*. We already know how to work with them. All properties that we've been using until now were data properties.
 
 The second type of properties is something new. It's *accessor properties*. They are essentially functions that work on getting and setting a value, but look like regular properties to an external code.
 
@@ -27,14 +27,14 @@ The getter works when `obj.propName` is read, the setter -- when it is assigned.
 
 For instance, we have a `user` object with `name` and `surname`:
 
-```js run
+```js
 let user ={
  name:"John",
  surname:"Smith"
 };
 ```
 
-Now we want to add a "fullName" property, that should be "John Smith". Of course, we don't want to copy-paste existing information, so we can implement it as an accessor:
+Now we want to add a `fullName` property, that should be `"John Smith"`. Of course, we don't want to copy-paste existing information, so we can implement it as an accessor:
 
 ```js run
 let user ={
@@ -55,7 +55,19 @@ alert(user.fullName); // John Smith
 
 From outside, an accessor property looks like a regular one. That's the idea of accessor properties. We don't *call*`user.fullName` as a function, we *read* it normally: the getter runs behind the scenes.
 
-As of now, `fullName` has only a getter. If we attempt to assign `user.fullName=`, there will be an error.
+As of now, `fullName` has only a getter. If we attempt to assign `user.fullName=`, there will be an error:
+
+```js run
+let user ={
+getfullName(){
+return`...`;
+ }
+};
+
+*!*
+user.fullName="Test"; // Error (property has only a getter)
+*/!*
+```
 
 Let's fix it by adding a setter for `user.fullName`:
 
@@ -82,25 +94,15 @@ alert(user.name); // Alice
 alert(user.surname); // Cooper
 ```
 
-Now we have a "virtual" property. It is readable and writable, but in fact does not exist.
-
-```smart header="Accessor properties are only accessible with get/set"
-Once a property is defined with `get prop()` or `set prop()`, it's an accessor property, not a data properety any more.
-
-- If there's a getter -- we can read `object.prop`, othrewise we can't.
-- If there's a setter -- we can set `object.prop=...`, othrewise we can't.
-
-And in either case we can't `delete` an accessor property.
-```
-
+As the result, we have a "virtual" property `fullName`. It is readable and writable.
 
 ## Accessor descriptors
 
-Descriptors for accessor properties are different -- as compared with data properties.
+Descriptors for accessor properties are different from those for data properties.
 
-For accessor properties, there is no `value`and`writable`, but instead there are `get` and `set` functions.
+For accessor properties, there is no `value`or`writable`, but instead there are `get` and `set` functions.
 
-So an accessor descriptor may have:
+That is, an accessor descriptor may have:
 
 -**`get`** -- a function without arguments, that works when a property is read,
 -**`set`** -- a function with one argument, that is called when the property is set,
@@ -132,7 +134,7 @@ alert(user.fullName); // John Smith
 for(let key in user) alert(key); // name, surname
 ```
 
-Please note once again that a property can be either an accessor or a data property, not both.
+Please note that a property can be either an accessor (has `get/set` methods) or a data property (has a `value`), not both.
 
 If we try to supply both `get` and `value` in the same descriptor, there will be an error:
 
@@ -151,9 +153,9 @@ Object.defineProperty({}, 'prop',{
 
 ## Smarter getters/setters
 
-Getters/setters can be used as wrappers over "real" property values to gain more control over them.
+Getters/setters can be used as wrappers over "real" property values to gain more control over operations with them.
 
-For instance, if we want to forbid too short names for `user`, we can store `name` in a special property `_name`. And filter assignments in the setter:
+For instance, if we want to forbid too short names for `user`, we can have a setter `name`and keep the value in a separate property `_name`:
 
 ```js run
 let user ={
@@ -176,14 +178,16 @@ alert(user.name); // Pete
 user.name=""; // Name is too short...
 ```
 
-Technically, the external code may still access the name directly by using `user._name`. But there is a widely known agreement that properties starting with an underscore `"_"` are internal and should not be touched from outside the object.
+So, the name is stored in `_name` property, and the access is done via getter and setter.
+
+Technically, external code is able to access the name directly by using `user._name`. But there is a widely known convention that properties starting with an underscore `"_"` are internal and should not be touched from outside the object.
 
 
 ## Using for compatibility
 
-One of the great ideas behind getters and setters -- they allow to take control over a "normal" data property and tweak it at any moment.
+One of the great uses of accessors is that they allow to take control over a "regular" data property at any moment by replacing it with a getter and a setter and tweak its behavior.
 
-For instance, we started implementing user objects using data properties `name` and `age`:
+Imagine we started implementing user objects using data properties `name` and `age`:
 
 ```js
 functionUser(name, age){
@@ -209,9 +213,11 @@ let john = new User("John", new Date(1992, 6, 1));
 
 Now what to do with the old code that still uses `age` property?
 
-We can try to find all such places and fix them, but that takes time and can be hard to do if that code is written by other people. And besides, `age` is a nice thing to have in `user`, right? In some places it's just what we want.
+We can try to find all such places and fix them, but that takes time and can be hard to do if that code is used by many other people. And besides, `age` is a nice thing to have in `user`, right?
+
+Let's keep it.
 
-Adding a getter for `age`mitigates the problem:
+Adding a getter for `age`solves the problem:
 
 ```js run no-beautify
 functionUser(name, birthday){