Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/topics/angular/topic.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ id: 'cbbb9857-d3fa-47b8-8b47-d91b3f3dde7f'
title: 'Angular'
status: 'accepted'
summary: 'Application setup, components, reactive state, services and HTTP integration.'
iconKey: 'architecture'
iconKey: 'angular'
domains:
- 'javascript'
kind: 'area'
Expand Down
8 changes: 8 additions & 0 deletions content/topics/javascript-async-await/sources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Authoring sources

- [MDN async function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) — returned Promises, synchronous entry, and the await-enabled function body.
- [MDN await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await) — accepted inputs, rejection behavior, suspension, and microtask continuations.
- [ECMAScript Await](https://tc39.es/ecma262/multipage/control-abstraction-objects.html#await) — suspension and resumption semantics.
- Local study guide: `study-library/generated/javascript-async-execution-and-reactivity/guide.md`, section 5, in the engineering-career repository.

2026-11-03 revision: the existing ready-value example now awaits the ordinary string '3' and shows 1 → outside → 3. The input table gives that concrete value, and a nearby callout separates unchanged result from deferred continuation. The already-fulfilled-Promise equivalence is retained. No additional timing example or topic-status change is introduced.
64 changes: 64 additions & 0 deletions content/topics/javascript-async-await/topic.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
id: '8cc54b47-6d86-479d-9c84-e5b702a4b8aa'
title: 'async and await'
status: 'accepted'
summary: 'What async changes, what await accepts, and when execution pauses and resumes.'
iconKey: 'async'
domains:
- 'javascript'
kind: 'concept'
childTopicIds:
- '30f56ccc-ceca-4590-8022-d81a3f3ca796'
relatedTopicIds:
- 'aa0d3bcb-7941-4636-b73c-806293b1d961'
- '33af9431-3a66-49d4-9cc7-87c3273a53bb'
---

## What does async change?

Adding `async` to a function does two things:

- **Every call returns a Promise.** A returned ordinary value becomes its fulfillment value; an uncaught throw rejects it. Returning another Promise makes it follow that Promise's outcome.
- **Allows `await` inside its body.**

> Calling an async function **starts its body immediately on the current JS thread**. `async` alone does not schedule the call for later or move its work to another thread.

## What does await pause?

`await expression` first **evaluates the expression now**, then suspends **only the current async function** while it waits for the outcome. It **does not block the JS thread**; the caller can continue.

- **Fulfillment:** the `await` expression produces the fulfilled value.
- **Rejection:** execution resumes by **throwing the rejection reason at the await point**. A surrounding `try`/`catch` can handle it; otherwise the async function's returned Promise rejects.

## Already ready still means resume later

```js
async function readValue() {
console.log(1);
const value = await '3';
console.log(value);
return value;
}

const result = readValue(); // result is a Promise
console.log('outside');
// 1 → outside → 3
```

Awaiting an **already fulfilled Promise**, such as `Promise.resolve('3')`, likewise
resumes later. A pending Promise must settle first.

## What can await accept?

A **thenable** is an object with a callable `.then` method.

| Input | Result |
| ------------------------------ | -------------- |
| **Promise** | Value or throw |
| **Thenable** | Value or throw |
| **Ordinary value**, e.g. `'3'` | Same `'3'` |

> **Awaiting an ordinary value still suspends the current async function.**
> The result is unchanged; execution still resumes later as a microtask.

`await` is also available at the top level of a JavaScript module; `async` is needed to use it inside a function.
8 changes: 8 additions & 0 deletions content/topics/javascript-async-concurrency/sources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Authoring sources

Retrieval job: choose sequential await, Promise.all, or Promise.allSettled from operation dependencies and required failure behavior.

- [ECMAScript Await](https://tc39.es/ecma262/multipage/control-abstraction-objects.html#await) — suspension of the current function.
- [ECMAScript Promise.all](https://tc39.es/ecma262/multipage/control-abstraction-objects.html#sec-promise.all) — ordered result values and rejection before other inputs settle; no cancellation step.
- [ECMAScript Promise.allSettled](https://tc39.es/ecma262/multipage/control-abstraction-objects.html#sec-promise.allsettled) — waits for every input and preserves input order with status records.
- [Fetch Standard: abort fetch](https://fetch.spec.whatwg.org/#abort-fetch) — operation-specific cancellation through a signal.
59 changes: 59 additions & 0 deletions content/topics/javascript-async-concurrency/topic.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
id: '30f56ccc-ceca-4590-8022-d81a3f3ca796'
title: 'Sequential versus concurrent async work'
status: 'accepted'
summary: 'Choose sequential await, Promise.all, or Promise.allSettled according to dependencies and failure requirements.'
iconKey: 'async'
domains:
- 'javascript'
kind: 'decision-aid'
childTopicIds: []
relatedTopicIds:
- '473801af-5283-41fe-9010-4ce462907f01'
---

| Need | Choose |
| --------------------------------------------------------------------- | ---------------------- |
| Next operation **needs the previous result** | Sequential `await` |
| Independent operations; **all must succeed** | `Promise.all()` |
| Independent operations; **inspect every outcome**, including failures | `Promise.allSettled()` |

Here, each `get…()` helper **starts a network request** and returns a Promise for its response data.

## Sequential — dependent requests

```js
async function loadOrders() {
const user = await getUser(); // Request the user; wait for their data.
return getOrders(user.id); // Then request orders using that user's ID.
}
```

`await loadOrders()` receives the orders **after both requests finish**.

## Concurrent — independent requests

```js
async function loadCatalog() {
const products = getProducts();
const categories = getCategories(); // Starts before products finishes.
return Promise.all([products, categories]);
}
```

**The function calls start these operations; `Promise.all()` joins their results.** Passing `[getProducts, getCategories]` passes functions—it does not call them.

**Both requests can be in progress at the same time.** The function calls that start them still run one after the other.

## What if one fails?

| Join | Fulfillment value | On an input rejection |
| ---------------------- | ------------------ | ---------------------------------- |
| `Promise.all()` | `[valueA, valueB]` | **Rejects on the first rejection** |
| `Promise.allSettled()` | Outcome records | **Waits for all inputs** |

An `allSettled` record is `{ status: 'fulfilled', value }` or `{ status: 'rejected', reason }`.

Both result arrays preserve **input order**, regardless of completion order. `allSettled` stays pending if an input never settles.

> **`Promise.all()` rejecting does not cancel the other operations.** Cancellation needs support from the operation, such as `fetch` with an `AbortSignal`.
241 changes: 241 additions & 0 deletions content/topics/javascript-event-loop/execution-cycle.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
12 changes: 12 additions & 0 deletions content/topics/javascript-event-loop/sources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Authoring references

Retrieval job: identify what is scheduled as a task or microtask and determine the ordinary execution order. Scope: guide section 2 and requested discussion clarifications. The sequence is explicitly simplified; checkpoints can also occur after callback cleanup with an empty JS stack.

- [HTML event loops and processing model](https://html.spec.whatwg.org/multipage/webappapis.html#event-loops): task sources, task queues, checkpoints, rendering opportunities.
- [MDN microtask guide](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide): draining, enqueue order, queueMicrotask, Promise and observer callbacks.
- Local study guide: `engineering-career/study-library/generated/javascript-async-execution-and-reactivity/guide.md`, section 2.

- [ECMAScript Await operation](https://tc39.es/ecma262/multipage/control-abstraction-objects.html#await): awaits an ordinary native Promise through a continuation reaction.
- [PerformPromiseThen](https://tc39.es/ecma262/multipage/control-abstraction-objects.html#sec-performpromisethen): pending reactions are registered until settlement; already fulfilled Promises enqueue their reactions immediately.

2026-11-02 revision: compare the same direct async call and then registration in opposite orders, using one already fulfilled native Promise. The queue labels identify [a, b] versus [b, a]; synchronous 1 precedes both. Each case runs separately. A returned-Promise dependency supplies explicit sequencing. Agent-run checks confirm both outputs; the existing topic status is preserved.
97 changes: 97 additions & 0 deletions content/topics/javascript-event-loop/topic.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
---
id: '42c5c1eb-ad74-4a0c-87eb-817949c5cdbf'
title: 'Event loop, tasks, and microtasks'
status: 'accepted'
summary: 'How the browser schedules ready work and drains microtasks.'
iconKey: 'event-loop'
domains:
- 'javascript'
kind: 'concept'
childTopicIds:
- '33af9431-3a66-49d4-9cc7-87c3273a53bb'
relatedTopicIds: []
---

The **event loop** is the host's scheduling mechanism: it coordinates **when ready tasks run** and **when microtasks are drained**.

## The order to remember

![Simplified browser sequence: run a ready task to completion, run microtasks until the queue is empty including newly added ones, then the display may update. Painting is not guaranteed. Continue with more work; checkpoints also occur at other boundaries.](execution-cycle.svg)

## Callback, task, or microtask?

- **Callback:** **the function** passed to another API.
- **Task:** **host-scheduled work**, such as dispatching a user interaction or invoking a timer callback.
- **Microtask:** work placed in a **separate queue**, such as invoking a Promise handler. It runs **after current synchronous execution finishes, before another task starts**.

A **timer callback** is the function passed to `setTimeout` or `setInterval`—not the registration call itself.

## What is a microtask checkpoint?

A checkpoint is **when the browser drains the microtask queue**. In the ordinary script/callback examples here, this happens after current synchronous execution finishes and the JS stack is empty.

- Microtasks run in **enqueue order**.
- Microtasks added while draining **run in the same checkpoint**.
- Draining stops **only when the queue is empty**. Continually adding microtasks can **delay other tasks and rendering**.

Checkpoints also occur at other specified boundaries; they are **not limited to one checkpoint per task**.

## Common microtask sources

- **Promise handlers:** `.then()`, `.catch()`, and `.finally()`, once the relevant Promise settles.
- **After `await`:** resuming the async function when the awaited outcome is ready—even if it was already ready.
- **`queueMicrotask(callback)`:** explicitly queues a callback.
- **`MutationObserver`:** delivery of mutation notifications to observer callbacks.

```js
console.log('start');
setTimeout(() => console.log('timer'), 0);
Promise.resolve().then(() => console.log('promise'));
console.log('end');
// start → end → promise → timer
```

## `await` or `.then()`: which runs first?

**Compare when their microtasks are queued.** Run each case separately with this
setup, using an **already fulfilled native Promise**:

```js
const ready = Promise.resolve();

async function somefun() {
console.log(1);
await ready;
console.log('a');
}
```

**Reach `await` first → queue `[a, b]`:**

```js
somefun();
ready.then(() => console.log('b'));
// 1 → a → b
```

**Register `.then()` first → queue `[b, a]`:**

```js
ready.then(() => console.log('b'));
somefun();
// 1 → b → a
```

**`1` prints synchronously in both cases.** Calling `.then()` queues its callback;
it does not run it inline. Both `a` and `b` wait until current synchronous execution
finishes. A pending awaited Promise must settle before its continuation is queued.

To require `b` after `a`, attach the handler to **the function's returned Promise**:
`somefun().then(() => console.log('b'))`.

## Tasks do not share one global FIFO

Browsers have multiple task sources and task queues. There is no single global FIFO
ordering every timer, network event, and click.

**Registration order alone does not guarantee execution order across different task sources.**
Loading
Loading