types-grammar: filling out content in chapter 3, as well as adding related clarifications in chapters 1 and 2

Author: getify

types-grammar/README.md

@@ -8,8 +8,8 @@
 
 * [Foreword](foreword.md) (by TBA)
 * [Preface](../preface.md)
-* [Chapter 1: Primitives](ch1.md)
-* [Chapter 2: Value Behaviors](ch2.md)
+* [Chapter 1: Primitive Values](ch1.md)
+* [Chapter 2: Primitive Behaviors](ch2.md)
 * [Chapter 3: Object Values](ch3.md)
 * [Chapter 4: Coercing Values](ch4.md)
 * Chapter 5: TODO

types-grammar/ch1.md

@@ -1,5 +1,5 @@
 # You Don't Know JS Yet: Types & Grammar - 2nd Edition
-# Chapter 1: Primitives
+# Chapter 1: Primitive Values
 
 | NOTE: |
 | :--- |
@@ -13,17 +13,17 @@ Here, we'll look at the core value types of JS, specifically the non-object type
 
 JS doesn't apply types to variables or properties -- what I call, "container types" -- but rather, values themselves have types -- what I call, "value types".
 
-The language provides seven built-in, primitive (non-object) value types:
+The language provides seven built-in, primitive (non-object) value types: [^PrimitiveValues]
 
-* `null`
 * `undefined`
+* `null`
 * `boolean`
-* `string`
 * `number`
 * `bigint`
 * `symbol`
+* `string`
 
-These value-types define collections of one or more concrete values, each with a set of shared behaviors for all values of that type.
+These value-types define collections of one or more concrete values, each with a set of shared behaviors for all values of each type.
 
 ### Type-Of
 
@@ -48,6 +48,48 @@ typeof greeting;        // "string"
 
 JS variables themselves don't have types. They hold any arbitrary value, which itself has a value-type.
 
+### Non-objects?
+
+What specifically makes the 7 primitive value types distinct from the object value types (and sub-types)? Why shouldn't we just consider them all as essentially *objects* under the covers?
+
+Consider:
+
+```js
+myName = "Kyle";
+
+myName.nickname = "getify";
+
+console.log(myName.nickname);           // undefined
+```
+
+This snippet appears to silently fail to add a `nickname` property to a primitive string. Taken at face value, that might imply that primitives are really just objects under the covers, as many have (wrongly) asserted over the years.
+
+| WARNING: |
+| :--- |
+| One might explain that silent failure as an example of *auto-boxing* (see "Automatic Objects" in Chapter 3), where the primitive is implicitly converted to a `String` instance wrapper object while attempting to assign the property, and then this internal object is thrown away after the statement completes. In fact, I said exactly that in the first edition of this book. But I was wrong; oops! |
+
+Something deeper is at play, as we see in this version of the previous snippet:
+
+```js
+"use strict";
+
+myName = "Kyle";
+
+myName.nickname = "getify";
+// TypeError: Cannot create property 'nickname'
+// on string 'Kyle'
+```
+
+Interesting! In strict-mode, JS enforces a restriction that disallows setting a new property on a primitive value, as if implicitly promoting it to a new object.
+
+By contrast, in non-strict mode, JS allows the violation to go unmentioned. So why? Because strict-mode was added to the language in ES5.1 (2011), more than 15 years in, and such a change would have broken existing programs had it not been defined as sensitive to the new strict-mode declaration.
+
+So what can we conclude about the distinction between primitives and objects? Primitives are values that *are not allowed to have properties*; only objects are allowed such.
+
+| TIP: |
+| :--- |
+| This particular distinction seems to be contradicted by expressions like `"hello".length`; even in strict-mode, it returns the expected value `5`. So it certainly *seems* like the string has a `length` property! But, as just previously mentioned, the correct explanation is *auto-boxing*; we'll cover the topic in "Automatic Objects" in Chapter 3. |
+
 ## Empty Values
 
 The `null` and `undefined` types both typically represent an emptiness or absence of value.
@@ -1108,12 +1150,28 @@ If the registry doesn't have a symbol under that specified *key*, a new symbol (
 
 Going in the opposite direction, if you have the symbol value itself, and want to retrieve the *key* it's registered under, `Symbol.keyFor(..)` takes the symbol itself as input, and returns the *key* (if any). That's useful in case it's more convenient to pass around the *key* string value than the symbol itself.
 
+### Object or Primitive?
+
+Unlike other primitives like `42`, where you can create multiple copies of the same value, symbols *do* act more like specific object references in that they're always completely unique (for purposes of value assignment and equality comparison). The specification also categorizes the `Symbol()` function under the "Fundamental Objects" section, calling the function a "constructor", and even defining its `prototype` property.
+
+However, as mentioned earlier, `new` cannot be used with `Symbol(..)`; this is similar to the `BigInt()` "constructor". We clearly know `bigint` values are primitives, so `symbol` values seem to be of the same *kind*.
+
+And in the specification's "Terms and Definitions", it lists symbol as a primitive value. [^PrimitiveValues] Moreover, the values themselves are used in JS programs as primitives rather than objects. For example, symbols are primarily used as keys in objects -- we know objects cannot use other object values as keys! -- along with strings, which are also primitives.
+
+As mentioned earlier, some JS engines even internally implement symbols as unique, monotonically incrementing integers (primitives!).
+
+Finally, as explained at the top of this chapter, we know primitive values are *not allowed* to have properties set on them, but are *auto-boxed* (see "Automatic Objects" in Chapter 3) internally to the corresponding object-wrapper type to facilitate property/method access. Symbols follow all these exact behaviors, the same as all the other primitives.
+
+All this considered, I think symbols are *much more* like primitives than objects, so that's how I present them in this book.
+
 ## Primitives Are Built-In Types
 
 We've now dug deeply into the seven primitive (non-object) value types that JS provides automatically built-in.
 
 Before we move on to discussing JS's built-in object value type, we want to take a closer look at the kinds of behaviors we can expect from JS values. We'll do so in-depth, in the next chapter.
 
+[^PrimitiveValues]: "4.4.5 primitive value", ECMAScript 2022 Language Specification; https://tc39.es/ecma262/#sec-primitive-value ; Accessed August 2022
+
 [^UTFUCS]: "JavaScript’s internal character encoding: UCS-2 or UTF-16?"; Mathias Bynens; January 20 2012; https://mathiasbynens.be/notes/javascript-encoding ; Accessed July 2022
 
 [^IEEE754]: "IEEE-754"; https://en.wikipedia.org/wiki/IEEE_754 ; Accessed July 2022

types-grammar/ch2.md

@@ -1,5 +1,5 @@
 # You Don't Know JS Yet: Types & Grammar - 2nd Edition
-# Chapter 2: Value Behaviors
+# Chapter 2: Primitive Behaviors
 
 | NOTE: |
 | :--- |
@@ -98,7 +98,7 @@ Additionally, most of the primitive value-types define their own methods with sp
 
 | NOTE: |
 | :--- |
-| Technically, these sorts of property/method accesses on primitive values are facilitated by an implicit coercive behavior called *auto-boxing*, which we'll cover in the next chapter. |
+| As already briefly mentioned in Chapter 1, technically, these sorts of property/method accesses on primitive values are facilitated by an implicit coercive behavior called *auto-boxing*. We'll cover this in detail in "Automatic Objects" in Chapter 3. |
 
 ## Primitive Assignments
 

types-grammar/ch3.md

@@ -7,26 +7,207 @@
 
 Now that we're comfortable with the built-in primitive types, we turn our attention to the `object` types in JS.
 
-The "Objects & Classes" title of this series covers objects in-depth already, so make sure you've read that before continuning with this chapter. Here we'll focus our attention on how the `object` value-type behaves and interacts with other values in JS.
+I could write a whole book talking about objects in-depth; in fact, I already did! The "Objects & Classes" title of this series covers objects in-depth already, so make sure you've read that before continuning with this chapter.
 
-## Nature Of Objects
+Rather than repeat that book's content, here we'll focus our attention on how the `object` value-type behaves and interacts with other values in JS.
 
-The `object` value-type comprises several sub-types with specialized behaviors. These include:
+## Types of Objects
 
-* general objects
+The `object` value-type comprises several sub-types, each with specialized behaviors, including:
+
+* plain objects
 * fundamental objects (boxed primitives)
+* built-in objects
 * arrays
 * regular expressions
 * functions (aka, "callable objects")
 
-But one shared characteristic is that all objects are capable of acting as collections of values.
+Beyond the specialized behaviors, one shared characteristic is that all objects can act as collections (of properties) holding values (including functions/methods).
 
-// TODO
+## Plain Objects
+
+The general object value-type is sometimes referred to as *plain ol' javascript objects* (POJOs).
+
+Plain objects have a literal form:
+
+```js
+address = {
+    street: "12345 Market St",
+    city: "San Francisco",
+    state: "CA",
+    zip: "94114"
+};
+```
+
+This plain object (POJO), as defined with the `{ .. }` curly braces, is a collection of named properties (`street`, `city`, `state`, and `zip`). Properties can hold any values, primitives or other objects (including arrays, functions, etc).
+
+The same object could also have been defined imperatively using the `new Object()` constructor:
+
+```js
+address = new Object();
+address.street = "12345 Market St";
+address.city = "San Francisco";
+address.state = "CA";
+address.zip = "94114";
+```
+
+Plain objects are by default `[[Prototype]]` linked to `Object.prototype`, giving them delegated access to several general object methods, such as:
+
+* `toString()` / `toLocaleString()`
+* `valueOf()`
+* `isPrototypeOf(..)`
+* `hasOwnProperty(..)` (recently deprecated -- alternative: static `Object.hasOwn(..)` utility)
+* `propertyIsEnumerable(..)`
+* `__proto__` (getter function)
+
+```js
+address.isPrototypeOf(Object.prototype);    // true
+address.isPrototypeOf({});                  // false
+```
 
 ## Fundamental Objects
 
-In Chapter 2, I briefly mentioned *auto-boxing*, which we'll now revisit. [^AutoBoxing]
+JS defines several *fundamental* object types, which are instances of various built-in constructors, including:
+
+* `new String()`
+* `new Number()`
+* `new Boolean()`
+
+Note that these constructors must be used with the `new` keyword to construct instances of the fundamental objects. Otherwise, these functions actually perform type coercion (see Chapter 4).
+
+These fundamental object constructors create object value-types instead of a primitives:
+
+```js
+myName = "Kyle";
+typeof myName;                      // "string"
+
+myNickname = new String("getify");
+typeof myNickname;                  // "object"
+```
+
+In other words, an instance of a fundamental object constructor can actually be seen as a wrapper around the corresponding underlying primitive value.
+
+| WARNING: |
+| :--- |
+| It's nearly universally regarded as *bad practice* to ever directly instantiate these fundamental objects. The primitive counterparts are generally more predictable, more performant, and offer *auto-boxing* (see "Automatic Objects" section below) whenever the underlying object-wrapper form is needed for property/method access. |
+
+The `Symbol(..)` and `BigInt(..)` functions are referred to in the specification as "constructors", though they're not used with the `new` keyword, and the values they produce in a JS program are indeed primitives.
+
+How, there are internal *fundamental objects* for these two types, used for prototype delegation and *auto-boxing*.
+
+By contrast, for `null` and `undefined` primitive values, there aren't `Null()` or `Undefined()` "constructors", nor corresponding fundamental objects or prototypes.
+
+### Prototypes
+
+Instances of the fundamental object constructors are `[[Prototype]]` linked to their constructors' `prototype` objects:
+
+* `String.prototype`: defines `length` property, as well as string-specific methods, like `toUpperCase()`, etc.
+
+* `Number.prototype`: defines number-specific methods, like `toPrecision(..)`, `toFixed(..)`, etc.
+
+* `Boolean.prototype`: defines default `toString()` and `valueOf()` methods.
+
+* `Symbol.prototype`: defines `description` (getter), as well as default `toString()` and `valueOf()` methods.
+
+* `BigInt.prototype`: defines default `toString()`, `toLocaleString()`, and `valueOf()` methods.
+
+Any direct instance of the built-in constructors have `[[Prototype]]` delegated access to its respective `prototype` properties/methods. Moreover, corresponding primitive values also have such delegated access, by way of *auto-boxing*.
+
+### Automatic Objects
+
+I've mentioned *auto-boxing* several times (including Chapters 1 and 2, and a few times so far in this chapter). It's finally time for us to explain that concept.
+
+Accessing a property or method on a value requires that the value be an object. As we've already seen in Chapter 1, primitives *are not* objects, so JS needs to then temporarily convert/wrap such a primitive to its fundamental object counterpart[^AutoBoxing] to perform that access.
+
+For example:
+
+```js
+myName = "Kyle";
+
+myName.length;              // 4
+
+myName.toUpperCase();       // "KYLE"
+```
+
+Accessing the `length` property or the `toUpperCase()` method, is only allowed on a primitive string value because JS *auto-boxes* the primitive `string` into a wrapper fundamental object, an instance of `new String(..)`. Otherwise, all such accesses would have to fail, since primitives do not have any properties.
+
+More importantly, when the primitive value is *auto-boxed* to its fundamental object counterpart, those internally created objects have access to predefined properties/methods (like `length` and `toUpperCase()`) via a `[[Prototype]]` link to their respective fundamental object's prototype.
+
+So an *auto-boxed* `string` is an instance of `new String()`, and is thus linked to `String.prototype`. Further, the same is true of `number` (wrapped as an instance of `new Number()`) and `boolean` (wrapped as an instance of `new Boolean()`).
+
+Even though the `Symbol(..)` and `BigInt(..)` "constructors" (used without `new`produce primitive values, these primitive values can also be *auto-boxed* to their internal fundamental object wrapper forms, for the purposes of delegated access to properties/methods.
+
+| NOTE: |
+| :--- |
+| See the "Objects & Classes" book of this series for more on `[[Prototype]]` linkages and delegated/inherited access to the fundamental object constructors' prototype objects. |
+
+Since `null` and `undefined` have no corresponding fundamental objects, there is no *auto-boxing* of these values.
+
+A subjective question to consider: is *auto-boxing* a form of coercion? I say it is, though some disagree. Internally, a primitive is converted to an object, meaning a change in value-type has occurred. Yes, it's temporary, but plenty of coercions are temporary. Moreover, the conversion is rather *implicit* (implied by the property/method access, but only happens internally). We'll revisit the nature of coercion in Chapter 4.
+
+## Other Built-in Objects
+
+In addition to fundamental object constructors, JS defines a number of other built-in constructors that create further specialized object sub-types:
+
+* `new Date(..)`
+* `new Error(..)`
+* `new Map(..)`, `new Set(..)`, `new WeakMap(..)`, `new WeakSet(..)` -- keyed collections
+* `new Int8Array(..)`, `new Uint32Array(..)`, etc -- indexed, typed-array collections
+* `new ArrayBuffer(..)`, `new SharedArrayBuffer(..)`, etc -- structured data collections
+
+## Arrays
+
+Arrays are objects that are specialized to behave as numerically indexed collections of values, as opposed to holding values at named properties like plain objects do.
+
+Arrays have a literal form:
+
+```js
+favoriteNumbers = [ 3, 12, 42 ];
+
+favoriteNumbers[2];                 // 42
+```
+
+The same array could also have been defined imperatively using the `new Array()` constructor:
+
+```js
+favoriteNumbers = new Array();
+favoriteNumbers[0] = 3;
+favoriteNumbers[1] = 12;
+favoriteNumbers[2] = 42;
+```
+
+Arrays are `[[Prototype]]` linked to `Array.prototype`, giving them delegated access to a variety of array-oriented methods, such as `map(..)`, `includes(..)`, etc:
+
+```js
+favoriteNumbers.map(v => v * 2);
+// [ 6, 24, 84 ]
+
+favoriteNumbers.includes(42);       // true
+```
+
+Some of the methods defined on `Array.prototype` -- for example, `push(..)`, `pop(..)`, `sort(..)`, etc -- behave by modifying the array value in place. Other methods -- for example, `concat(..)`, `map(..)`, `slice(..)` -- behave by creating a new array to return, leaving the original array intact. A third category of array functions -- for example, `indexOf(..)`, `includes(..)`, etc -- merely computes and returns a (non-array) result.
+
+## Regular Expressions
 
 // TODO
 
+## Functions
+
+// TODO
+
+## Proposed: Records/Tuples
+
+At the time of this writing, a (stage-2) proposal[^RecordsTuplesProposal] exists to add a new set of features to JS, which correspond closely to plain objects and arrays, but with some notable differences.
+
+Records are similar to plain objects, but are immutable (sealed, read-only), and (unlike objects) are treated as primitive values, for the purposes of value assignment and equality comparison. The syntax difference is a `#` before the `{ }` delimiter. Records can only contain primitive values (including records and tuples).
+
+Tuples have exactly the same relationship, but to arrays, including the `#` before the `[ ]` delimiters.
+
+It's important to note that while these look and seem like objects/arrays, they are indeed primitive (non-object) values.
+
+[^FundamentalObjects]: "20 Fundamental Objects", EcamScript 2022 Language Specification; https://262.ecma-international.org/13.0/#sec-fundamental-objects ; Accessed August 2022
+
 [^AutoBoxing]: "6.2.4.6 PutValue(V,W)", Step 5.a, ECMAScript 2022 Language Specification; https://262.ecma-international.org/13.0/#sec-putvalue ; Accessed August 2022
+
+[^RecordsTuplesProposal]: "JavaScript Records & Tuples Proposal"; Robin Ricard, Rick Button, Nicolò Ribaudo;
+https://github.com/tc39/proposal-record-tuple ; Accessed August 2022

types-grammar/toc.md

@@ -8,7 +8,7 @@
 
 * Foreword
 * Preface
-* Chapter 1: Primitives
+* Chapter 1: Primitive Values
 	* Value Types
     * Empty Values
     * Boolean Values
@@ -17,15 +17,21 @@
     * BigInteger Values
     * Symbol Values
     * Primitives Are Built-In Types
-* Chapter 2: Value Behaviors
+* Chapter 2: Primitive Behaviors
     * Primitive Immutability
     * Primitive Assignments
     * String Behaviors
     * Number Behaviors
     * Primitives Are Foundational
 * Chapter 3: Object Values
-    * Nature Of Objects
+    * Types of Objects
+    * Plain Objects
     * Fundamental Objects
+    * Other Built-in Objects
+    * Arrays
+    * Regular Expressions
+    * Functions
+    * Proposed: Records/Tuples
     * TODO
 * Chapter 4: Coercing Values
     * Coercion: Explicit vs Implicit