# 📘 ECMAScript Spec Language Cheat Sheet

A quick reference for understanding the abstract language used in the ECMAScript (JavaScript) specification, especially when reading sections like `IsLooselyEqual`.

---

## 🔣 Prefix Operators

| Symbol | Meaning                                                                 | Example               | Plain English                                               |
|--------|-------------------------------------------------------------------------|------------------------|-------------------------------------------------------------|
| `!`    | **Assert completion**: Must complete normally (if it throws, re-throw) | `! ToNumber(x)`        | “Convert x to a number. If it fails, throw the error.”      |
| `?`    | **Maybe error**: Propagate abrupt completions if thrown                | `? ToObject(value)`    | “Try converting. If it throws, return the error.”           |
| `~`    | **Completion record**: Extract the value from a record                 | `~ SomeOp()`           | “Get the value part of this result.”                        |

---

## 🛠️ Abstract Operations (Built-in Helpers)

These are internal helper operations defined in the spec.

| Operation        | Description                                                      | Example                            |
|------------------|------------------------------------------------------------------|------------------------------------|
| `ToNumber(x)`    | Convert `x` to a number using JavaScript coercion rules          | `ToNumber("5")` → `5`              |
| `ToPrimitive(x)` | Convert object `x` to a primitive (string/number/symbol)         | `ToPrimitive([1])` → `"1"`         |
| `ToObject(x)`    | Wrap primitive `x` in its object form                            | `ToObject("hi")` → `new String("hi")` |
| `Type(x)`        | Get internal type of value                                       | `Type(42)` → `"Number"`            |
| `SameValue(x, y)`| Like `===`, but also says `NaN === NaN`                          | `SameValue(NaN, NaN)` → `true`     |

---

## 🧾 Control and Declaration Keywords

| Syntax                     | Description                                          | Example                             |
|---------------------------|------------------------------------------------------|-------------------------------------|
| `Let x be ...`            | Declare a new variable                               | `Let n be ToNumber(y)`              |
| `Return X.`               | Exit the current operation with value `X`            | `Return true.`                      |
| `If condition, then:`     | Start an if block                                    | `If Type(x) is Number, then:`       |
| `Else:`                   | Standard else block                                  | `Else: Return false.`               |
| `Repeat:`                 | Infinite or conditional loop                         | `Repeat:` = `while (true)`          |
| `For each item of list:`  | Loop over a list                                     | `For each p of keys:`               |

---

## 🧠 Common Internal Type Names

These are what `Type(x)` might return.

| Type Name     | Corresponds to              |
|---------------|-----------------------------|
| `"Undefined"` | `undefined`                 |
| `"Null"`      | `null`                      |
| `"Boolean"`   | `true` or `false`           |
| `"Number"`    | Numeric values, incl. NaN   |
| `"BigInt"`    | Values like `123n`          |
| `"String"`    | Strings like `"hello"`      |
| `"Symbol"`    | `Symbol("id")`              |
| `"Object"`    | Arrays, functions, dates, etc. |

---

## 📦 Boxing and Conversion Helpers

| Operation               | Behavior                                   |
|-------------------------|--------------------------------------------|
| `ToNumber("5")`         | Convert string to number → `5`             |
| `ToPrimitive([1])`      | Call `.valueOf()` or `.toString()`         |
| `ToObject(42)`          | Wrap primitive → `new Number(42)`          |

---

## 🔄 Completion Records

Used internally to handle thrown values vs successful returns.

| Symbol | Behavior                            |
|--------|-------------------------------------|
| `!`    | Requires success; rethrow if error  |
| `?`    | Optional; bubble up errors if any   |
| `~`    | Extract value from a result object  |

---

## 🧪 Full Example Translation

From the spec:

```
6. If Type(x) is BigInt and Type(y) is String, then
   a. Let n be StringToBigInt(y).
   b. If n is undefined, return false.
   c. Return IsLooselyEqual(x, n).
```

### Plain English:
> If `x` is a BigInt and `y` is a string:
> - Try converting `y` to a BigInt (call it `n`)
> - If that fails (result is `undefined`), return `false`
> - Otherwise, compare `x` and `n` again using the same loose equality function

### Pseudocode:
```js
if (typeof x === 'bigint' && typeof y === 'string') {
  const n = BigInt(y); // assume conversion succeeds
  if (n === undefined) return false;
  return IsLooselyEqual(x, n);
}
```

---

## ✅ Summary

- The ECMAScript spec is written for engine implementers, not app developers.
- `!`, `?`, and `~` control how errors and completions are handled.
- Helper operations like `ToNumber`, `ToPrimitive`, and `Type(x)` are foundational.
- Each spec clause is like a mini-algorithm: structured, precise, and explicit.

---

**Author**: Rob's AI assistant  
**Source**: Adapted from [ECMAScript Specification](https://tc39.es/ecma262/)