Error Recovery

.eslintrc.cjs

@@ -19,32 +19,32 @@ module.exports = {
     '**/fixtures',
     '!**/.eslintrc.cjs',
   ],
-  parser: '@typescript-eslint/parser',
-  parserOptions: {
-    ecmaVersion: 'latest',
-    project: [],
-  },
-  settings: {
-    'import/parsers': {
-      '@typescript-eslint/parser': ['.js', '.cjs', '.mjs', '.mts', '.ts', '.d.ts'],
-    },
-    'import/resolver': {
-      typescript: {},
-    },
-    node: {
-      allowModules: ['@glimmer/debug', '@glimmer/local-debug-flags'],
-      tryExtensions: ['.js', '.ts', '.d.ts', '.json'],
-    },
-  },
-  plugins: [
-    '@typescript-eslint',
-    'prettier',
-    'qunit',
-    'simple-import-sort',
-    'unused-imports',
-    'prettier',
-    'n',
-  ],
+  // parser: '@typescript-eslint/parser',
+  // parserOptions: {
+  //   ecmaVersion: 'latest',
+  //   project: [],
+  // },
+  // settings: {
+  //   'import/parsers': {
+  //     '@typescript-eslint/parser': ['.js', '.cjs', '.mjs', '.mts', '.ts', '.d.ts'],
+  //   },
+  //   'import/resolver': {
+  //     typescript: {},
+  //   },
+  //   node: {
+  //     allowModules: ['@glimmer/debug', '@glimmer/local-debug-flags'],
+  //     tryExtensions: ['.js', '.ts', '.d.ts', '.json'],
+  //   },
+  // },
+  // plugins: [
+  //   '@typescript-eslint',
+  //   'prettier',
+  //   'qunit',
+  //   'simple-import-sort',
+  //   'unused-imports',
+  //   'prettier',
+  //   'n',
+  // ],
 
   rules: {},
   overrides: [

.prettierrc.json

@@ -1,5 +1,6 @@
 {
   "singleQuote": true,
   "trailingComma": "es5",
-  "printWidth": 100
+  "printWidth": 100,
+  "plugins": []
 }

TODO.md

@@ -0,0 +1,13 @@
+- [ ] Implement `#try` that takes handler
+  - [ ] internal `{{#if isClear}}{{!-- actual code --}}{{/if}}`
+  - [ ] if an error is encountered, unwind as-if isClear was false
+        during the render pass
+    - [ ] when you encounter the enter of the try, insert a marker in
+          every VM stack.
+    - [ ] every stack in the VM needs "unwind to nearest marker"
+    - [ ] when a render error is encountered, unwind all the stacks
+    - [ ] call the handler with the error
+  - [ ] no catch
+  - [ ] the handler has a way to clear the error
+  - [ ] deal with user destructors that should run even during render errors
+    - [ ] maintain the invariant that constructors and destructors are paired

benchmark/benchmarks/krausest/.eslintrc.cjs

@@ -0,0 +1,13 @@
+/** @type {import("eslint").Linter.Config} */
+module.exports = {
+  root: false,
+  overrides: [
+    {
+      files: ['**/*.js'],
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+      },
+    },
+  ],
+};

benchmark/benchmarks/krausest/package.json

@@ -1,5 +1,6 @@
 {
   "private": true,
+  "type": "module",
   "name": "@glimmer-workspace/krausest",
   "dependencies": {
     "@glimmer-workspace/benchmark-env": "workspace:^",

glimmer-vm.code-workspace

@@ -175,10 +175,6 @@
     {
       "name": "📦 @types/puppeteer-chromium-resolver",
       "path": "packages/@types/puppeteer-chromium-resolver"
-    },
-    {
-      "name": "📦 @types/qunit",
-      "path": "packages/@types/qunit"
     }
   ],
   "settings": {

guides/building-glimmer/01-introduction.md

@@ -0,0 +1,5 @@
+### Table of Contents
+
+1. [Introduction](./01-introduction.md)
+2. [Minification Assumptions](./02-minification.md)
+3. [Dev Mode Patterns](./03-devmode-patterns.md)

guides/building-glimmer/02-minification.md

@@ -0,0 +1,14 @@
+# Minification Assumptions
+
+> 🚧 https://terser.org/docs/options/
+
+- `import.meta.env.DEV`
+- `keep_fargs: false`
+
+## Issues
+
+### Works better in terser than swc
+
+- https://tiny.katz.zone/OfydPB
+- https://tiny.katz.zone/XlJrqp
+- https://tiny.katz.zone/6R5VdC (weird behavior involving new)

guides/building-glimmer/03-devmode-patterns.md

@@ -0,0 +1,3 @@
+# Dev Mode Patterns
+
+## Case Study: `DevMode<Description>`

guides/compiler-internals/01-introduction.md → guides/internals/01-introduction.md

@@ -6,3 +6,7 @@
 4. [Resolver Delegate](./04-compile-time-resolver-delegate.md)
 5. [Handles](./05-handles.md)
 6. [Template Compilation](./06-templates.md)
+7. [Frames and Blocks](./07-frames-and-blocks.md)
+8. [References](./08-references.md)
+9. [Error Recovery](./09-error-recovery/index.md)
+10. [Trace Logging](./10-trace-logging.md)

guides/internals/07-frames-and-blocks.md

@@ -0,0 +1,55 @@
+# Frames and Blocks
+
+Initial:
+
+```clj
+[
+  (PushFrame)
+  [
+    (ReturnTo END)
+    (Push ...Args)
+    (Enter)
+    [
+      (Assertion) ; (JumpUnless) | (AssertSame)
+      ...body
+    ]
+    (Exit)
+    (Return)
+    ; END
+  ]
+  (PopFrame)
+]
+```
+
+Update:
+
+```clj
+[
+  ; restore state
+  (ReturnTo -1)
+  (PushArgs ...Captured)
+  (ReEnter)
+  ; start evaluation here
+  [
+    (Assertion)
+    ; (JumpUnless) | (AssertSame)
+    ...body
+  ]
+  (Exit)
+  (Return)
+]
+```
+
+1. Initial
+   1. PushFrame
+   2. ReturnTo
+   3. Push captured args
+   4. Enter (optionally try frame)
+   5. Assertion
+      a. `JumpUnless` -> target
+      b. `AssertSame`
+   6. (body)
+   7. Exit
+   8. Return
+   9. PopFrame
+2. Update (from 1.5)

guides/internals/07-references.md

@@ -0,0 +1,139 @@
+# Reactivity APIs
+
+## Generic APIs
+
+## `readReactive`
+
+| Takes              | Returns                       |
+| ------------------ | ----------------------------- |
+| 🟢🟡 Fallible Read | 🟡 Result _(throws ⚪ Never)_ |
+
+The `readReactive` function takes a reactive value and returns a `ReactiveResult`.
+
+## `unwrapReactive`
+
+The `unwrapReactive` function takes a `ReactiveResult` and returns its value, throwing an exception
+if the reactive produces an error (or was previously an error).
+
+| Takes              | Returns                              |
+| ------------------ | ------------------------------------ |
+| 🟢🟡 Fallible Read | 🟢 Value _(throws 🔴 UserException)_ |
+
+## `updateReactive`
+
+The `updateReactive` function takes a _mutable_ reactive and a new value and updates it. You cannot
+pass an immutable reactive to this function.
+
+| Takes      | Updates                  |
+| ---------- | ------------------------ |
+| 📝 Mutable | 🟢 Value _(or 🔴 Error)_ |
+
+## Cell APIs
+
+### Constructors
+
+```ts
+function Cell(value: T): MutableCell<T>;
+function ReadonlyCell(value: T): ReadonlyCell<T>;
+
+type Cell<T> = MutableCell<T> | ReadonlyCell<T>;
+```
+
+| Type              | Read     | Write        |
+| ----------------- | -------- | ------------ |
+| `Cell<T>`         | 🟢 Value | 📝 Mutable   |
+| `ReadonlyCell<T>` | 🟢 Value | 🚫 Immutable |
+
+### `readCell`
+
+```ts
+export function readCell<T>(cell: Cell<T>): T;
+```
+
+The `readCell` function takes a cell and returns its value. Since cells are infallible, you can use
+this function to read from a cell without risking an exception (as with `unwrapReactive`).
+
+### `writeCell`
+
+```ts
+export function writeCell<T>(cell: MutableCell<T>, value: T): void;
+```
+
+| Takes            | Updates  |
+| ---------------- | -------- |
+| 📝 Mutable Write | 🟢 Value |
+
+The `writeCell` function writes a new value to a mutable cell. You can't write to a readonly cell.
+
+## Formula APIs
+
+| Type          | Read      | Write        |
+| ------------- | --------- | ------------ |
+| `Accessor<T>` | 🟡 Result | 📝 Mutable   |
+| `Formula<T>`  | 🟡 Result | 🚫 Immutable |
+
+### Constructors
+
+```ts
+export function Formula<T>(compute: () => T): Formula<T>;
+export function Accessor<T>(options: { get: () => T; set: (value: T) => void }): Accessor<T>;
+```
+
+If an accessor's `set` throws an error, the reactive value will become an error.
+
+## External Markers
+
+External markers are not reactive values themselves. Instead, they _stand in_ for external storage.
+
+Here's an example using a `SimpleMap` class that uses a `Map` as its backing storage:
+
+```ts
+class SimpleMap<K, V> {
+  #markers = new Map<K, ExternalMarker>();
+  #values = new Map<K, V>();
+
+  get(key: K): V {
+    this.#initialized(key).consumed();
+    return this.#values.get(key);
+  }
+
+  has(key: K) {
+    this.#initialized(key).consumed();
+    return this.#values.has(key);
+  }
+
+  set(key: K, value: V) {
+    this.#initialized(key).updated();
+    this.#values.set(key, value);
+  }
+
+  #initialized(key: K) {
+    let marker = this.#markers.get(key);
+
+    if (!marker) {
+      marker = ExternalMarker();
+      this.#markers.set(key, marker);
+    }
+
+    return marker;
+  }
+}
+```
+
+Now, reads from `has(key)` or `get(key)` will be invalidated whenever `set(key, value)` is called on
+the same key.
+
+The crux of the situation is that we don't want to store every value in a Cell and turn every
+computation into a `Formula`. Instead, we want to store our data in normal JavaScript data
+structures and notify the reactivity system whenever the data is accessed or modified.
+
+## Internal Reactives
+
+### `ComputedCell`
+
+A `ComputedCell` behaves like a cell, but it uses a `compute` function to compute a new value. The
+`compute` function must be infallible, and there is no error recovery if it fails.
+
+| Type              | Read     | Write        |
+| ----------------- | -------- | ------------ |
+| `ComputedCell<T>` | 🟢 Value | 🚫 Immutable |

guides/internals/09-error-recovery/A-error-recovery-references.md

@@ -0,0 +1,55 @@
+# Error Recovery: Reactive Values
+
+Reactive values are _fallible_: they can be in an error state.
+
+## `ReactiveResult<T>`
+
+A `ReactiveResult` can be in one of two states:
+
+```ts
+interface Ok<T> {
+  type: 'ok';
+  value: T;
+}
+```
+
+```ts
+interface Error {
+  type: 'error';
+  value: UserException;
+}
+```
+
+## General Reactive APIs
+
+### `readReactive`
+
+The `readReactive` function takes a reactive value and returns a `ReactiveResult`.
+
+### `unwrapReactive`
+
+The `unwrapReactive` function takes a `ReactiveResult` and returns its value, throwing an exception
+if the reactive produces an error (or was previously an error).
+
+## Cell APIs
+
+### `readCell`
+
+### `writeCell`
+
+## Error Recovery
+
+Once a formula has entered the error state, it can be recovered in one of two ways:
+
+- The formula invalidates
+- The `clearError` function is called
+
+Examples:
+
+```ts
+class isError = createCell(false);
+
+const formula = FallibleFormula(() => {
+  if ()
+});
+```