Asynchronous JS: Event Loop, Promises & Async/Await

+-------------------------------------------------------------------------+
|                  THE JAVASCRIPT ASYNCHRONOUS ARCHITECTURE               |
+-------------------------------------------------------------------------+
|                                                                         |
|  +-----------------------+              +----------------------------+  |
|  | CALL STACK (V8)       |              | HOST PLATFORM APIs         |  |
|  | - Single Thread       |              | - Browser: fetch, DOM,     |  |
|  | - Synchronous frames  |              |   setTimeout, indexedDB    |  |
|  | - LIFO execution      |              | - Node.js: Libuv Thread    |  |
|  |                       |              |   Pool, epoll, kqueue, fs  |  |
|  +-----------+-----------+              +-------------+--------------+  |
|              |                                        |                 |
|              | Dispatches Async Task                  | Completes I/O   |
|              +--------------------------------------->|                 |
|                                                       |                 |
|                                                       v                 |
|  +-------------------------------------------------------------------+  |
|  | QUEUE INFRASTRUCTURE                                              |  |
|  |                                                                   |  |
|  | 1. Microtask Queue (HIGHEST PRIORITY)                             |  |
|  |    Promise.then(), queueMicrotask(), process.nextTick()           |  |
|  |                                                                   |  |
|  | 2. Macrotask Queue (Task Queue)                                   |  |
|  |    setTimeout, setInterval, setImmediate, I/O events, UI clicks   |  |
|  +-----------------------------------+-------------------------------+  |
|                                      |                                  |
|                                      v                                  |
|  +-------------------------------------------------------------------+  |
|  | THE EVENT LOOP TICK ARBITRATION                                   |  |
|  |                                                                   |  |
|  | Loop Check:                                                       |  |
|  | 1. Is Call Stack empty?                                           |  |
|  |    - NO  --> Wait for current synchronous frame to finish.        |  |
|  |    - YES --> Proceed to Microtasks.                               |  |
|  | 2. DRAIN MICROTASKS: Run ALL pending microtasks until queue empty.|  |
|  | 3. Render Stage (Browser): Execute requestAnimationFrame & Paint. |  |
|  | 4. DEQUEUE ONE MACROTASK: Push 1 task to Call Stack and execute.  |  |
|  | 5. Repeat cycle indefinitely.                                     |  |
|  +-------------------------------------------------------------------+  |
|                                                                         |
+-------------------------------------------------------------------------+

// CATASTROPHIC ENGINE LOCKUP: Microtask Starvation!
function infiniteMicrotasks() {
  queueMicrotask(() => {
    infiniteMicrotasks(); // Recursively queues microtask!
  });
}
infiniteMicrotasks();

+-------------------------------------------------------------------------+
|                  TASK QUEUE ARBITRATION & SCHEDULING MATRIX             |
+---------------------+-------------------+-------------------------------+
| QUEUE TIER          | CONCRETE APIS     | DRAIN BEHAVIOR                |
+---------------------+-------------------+-------------------------------+
| 1. process.nextTick | process.nextTick()| Drained immediately after     |
|    (Node.js Only)   |                   | current operation, BEFORE any |
|                     |                   | other microtask runs.         |
+---------------------+-------------------+-------------------------------+
| 2. Standard         | Promise.then(),   | Drained completely after Call |
|    Microtask Queue  | catch(), finally()| Stack empties, BEFORE any     |
|                     | queueMicrotask()  | macrotask or UI render.       |
+---------------------+-------------------+-------------------------------+
| 3. Animation Queue  | requestAnimation- | Executed prior to physical    |
|    (Browser Only)   | Frame()           | screen display repaint.       |
+---------------------+-------------------+-------------------------------+
| 4. Macrotask Queue  | setTimeout(),     | Executed ONE AT A TIME.       |
|    (Task Queue)     | setInterval(),    | Microtasks drain after every  |
|                     | setImmediate(),   | individual macrotask!         |
|                     | I/O socket events |                               |
+---------------------+-------------------+-------------------------------+

+-------------------------------------------------------------------------+
|                  THE PROMISE FINITE STATE MACHINE (FSM)                 |
+-------------------------------------------------------------------------+
|                                                                         |
|                            +-----------------+                          |
|                            |     PENDING     |                          |
|                            | (Initial State) |                          |
|                            +--------+--------+                          |
|                                     |                                   |
|                  +------------------+------------------+                |
|                  |                                     |                |
|                  v (resolve(value))                    v (reject(error))|
|          +-----------------+                   +-----------------+      |
|          |    FULFILLED    |                   |    REJECTED     |      |
|          | (Settled State) |                   | (Settled State) |      |
|          +-----------------+                   +-----------------+      |
|                                                                         |
|  Irrevocability Invariant:                                              |
|  Once a Promise transitions from PENDING to FULFILLED or REJECTED,      |
|  its state is PERMANENTLY LOCKED. Subsequent calls to resolve()         |
|  or reject() are silently ignored.                                      |
|                                                                         |
+-------------------------------------------------------------------------+

// Synchronously fulfilled promise
const p = Promise.resolve(42);

p.then(val => console.log("Microtask output:", val));

console.log("Synchronous output");

// Console Output Order:
// 1. "Synchronous output"
// 2. "Microtask output: 42"

+-------------------------------------------------------------------------+
|                  THE FOUR PROMISE COMBINATOR PARADIGMS                  |
+---------------------+-------------------+-------------------------------+
| COMBINATOR          | RESOLVES WHEN     | REJECTS WHEN                  |
+---------------------+-------------------+-------------------------------+
| Promise.all()       | ALL promises      | ANY promise rejects           |
|                     | fulfill (Array)   | (Fail-Fast: first rejection)  |
+---------------------+-------------------+-------------------------------+
| Promise.allSettled()| ALL promises      | NEVER REJECTS!                |
|                     | settle (Fulfill   | Returns array of {status,     |
|                     | OR Reject)        | value|reason} status objects  |
+---------------------+-------------------+-------------------------------+
| Promise.race()      | FIRST promise     | FIRST promise rejects         |
|                     | fulfills          | (First settled promise wins)  |
+---------------------+-------------------+-------------------------------+
| Promise.any()       | FIRST promise     | ALL promises reject           |
|                     | fulfills          | (Throws AggregateError)       |
+---------------------+-------------------+-------------------------------+

async function fetchUserMetrics(userId) {
  console.log("A: Synchronous start");
  
  // Await pauses fetchUserMetrics, packages rest into microtask continuation
  const res = await Promise.resolve({ id: userId, score: 98 });
  
  console.log("B: Resumed in microtask:", res.score);
  return res.score;
}

console.log("1: Script start");
fetchUserMetrics(101);
console.log("2: Script end");

// Exact Execution Order:
// 1. "1: Script start"
// 2. "A: Synchronous start"
// 3. "2: Script end"
// 4. "B: Resumed in microtask: 98"

// CATASTROPHIC PERFORMANCE ANTI-PATTERN: Sequential Waterfall
// 10 items taking 200ms each = 2,000ms total latency!
async function fetchBatchBad(itemIds) {
  const results = [];
  for (const id of itemIds) {
    const data = await api.fetchItem(id); // Pauses loop sequentially!
    results.push(data);
  }
  return results;
}

// HIGH-PERFORMANCE CONCURRENT PATTERN
// 10 items executed in parallel = ~200ms total latency!
async function fetchBatchOptimized(itemIds) {
  const promises = itemIds.map(id => api.fetchItem(id));
  return await Promise.all(promises);
}

+-------------------------------------------------------------------------+
|                  THE ABORTCONTROLLER CANCELLATION MODEL                 |
+-------------------------------------------------------------------------+
|                                                                         |
|  const controller = new AbortController();                              |
|  const signal = controller.signal;                                      |
|                                                                         |
|  [ Consumer Component ]                 [ Asynchronous Worker ]         |
|  User clicks "Cancel Task"              Receives signal in fetch/loop   |
|         |                                      |                        |
|         v                                      |                        |
|  controller.abort()                            |                        |
|         |                                      |                        |
|         v                                      v                        |
|  Fires 'abort' event on signal ---------> Catches abort event           |
|                                           Throws DOMException           |
|                                           ("AbortError") immediately    |
|                                           Closes network socket         |
|                                                                         |
+-------------------------------------------------------------------------+

async function fetchWithDeadline(url, timeoutMs = 3000) {
  try {
    // Automatically cancels if network takes longer than 3 seconds
    const response = await fetch(url, {
      signal: AbortSignal.timeout(timeoutMs)
    });
    return await response.json();
  } catch (err) {
    if (err.name === "TimeoutError") {
      console.error(`Request timed out after {timeoutMs}ms`);
    } else if (err.name === "AbortError") {
      console.error("Request was explicitly aborted by user");
    } else {
      console.error("Network error:", err);
    }
    throw err;
  }
}

'''
Production-Grade Asynchronous Task Pool & Concurrency Limiter.
Demonstrates event loop queueing, Promise coordination, and cooperative cancellation.
'''

// =====================================================================
// 1. CONCURRENCY LIMITER (PROMISE POOL)
// =====================================================================

class ConcurrencyLimiter {
  constructor(maxConcurrency = 5) {
    this.maxConcurrency = maxConcurrency;
    this.activeCount = 0;
    this.queue = [];
  }

  '''
  Enqueues an asynchronous task generator function.
  Resolves when the task executes within concurrency bounds.
  '''
  run(taskFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ taskFn, resolve, reject });
      this.dispatch();
    });
  }

  dispatch() {
    // If under concurrency threshold and tasks remain in queue
    while (this.activeCount < this.maxConcurrency && this.queue.length > 0) {
      const { taskFn, resolve, reject } = this.queue.shift();
      this.activeCount++;

      // Execute task
      taskFn()
        .then(resolve)
        .catch(reject)
        .finally(() => {
          this.activeCount--;
          // Dequeue next task
          this.dispatch();
        });
    }
  }

  getPendingCount() {
    return this.queue.length;
  }

  getActiveCount() {
    return this.activeCount;
  }
}


// =====================================================================
// 2. RESILIENT TASK WITH RETRY & EXPONENTIAL BACKOFF + JITTER
// =====================================================================

async function executeWithRetry(operation, maxRetries = 3, baseDelayMs = 50, signal = null) {
  let attempt = 0;

  while (attempt < maxRetries) {
    // Check if cancellation signal fired
    if (signal && signal.aborted) {
      throw new Error(`Operation aborted: {signal.reason}`);
    }

    try {
      return await operation();
    } catch (err) {
      attempt++;
      if (attempt >= maxRetries) {
        throw new Error(`Failed after {maxRetries} attempts. Last error: {err.message}`);
      }

      // Calculate exponential backoff with full jitter
      const expDelay = baseDelayMs * Math.pow(2, attempt);
      const jitter = Math.random() * expDelay;
      const totalWaitMs = expDelay + jitter;

      console.warn(`[Retry Warning] Attempt {attempt} failed: {err.message}. Retrying in {totalWaitMs.toFixed(0)}ms...`);

      // Sleep cooperative with abort signal
      await new Promise((res, rej) => {
        const timer = setTimeout(res, totalWaitMs);
        if (signal) {
          signal.addEventListener("abort", () => {
            clearTimeout(timer);
            rej(new Error(`Operation aborted during backoff: {signal.reason}`));
          }, { once: true });
        }
      });
    }
  }
}


// =====================================================================
// 3. VERIFICATION HARNESS & BENCHMARK
// =====================================================================

async function main() {
  console.log("=== ASYNCHRONOUS TASK POOL & CONCURRENCY BENCHMARK ===");

  const TOTAL_TASKS = 20;
  const MAX_CONCURRENT = 3;
  const limiter = new ConcurrencyLimiter(MAX_CONCURRENT);

  const controller = new AbortController();
  const startTime = performance.now();

  // Mock I/O operation
  const createMockTask = (taskId) => async () => {
    // Simulate network latency (between 60ms and 140ms)
    const latency = Math.floor(Math.random() * 80) + 60;
    
    // Simulate intermittent failure for Task 4 to demonstrate retry
    if (taskId === 4 && Math.random() > 0.3) {
      throw new Error("HTTP 503 Service Unavailable");
    }

    await new Promise(res => setTimeout(res, latency));
    return { taskId, latency, completedAt: (performance.now() - startTime).toFixed(1) + "ms" };
  };

  console.log(`Submitting {TOTAL_TASKS} tasks to limiter (Max concurrency: {MAX_CONCURRENT})...\n`);

  // Launch all tasks through limiter
  const taskPromises = [];
  for (let i = 1; i <= TOTAL_TASKS; i++) {
    const task = createMockTask(i);
    // Wrap with retry and concurrency bounds
    const execution = limiter.run(() => executeWithRetry(task, 3, 40, controller.signal));
    taskPromises.push(execution);
  }

  // Await all pooled tasks
  const results = await Promise.allSettled(taskPromises);

  const totalTime = (performance.now() - startTime).toFixed(2);
  console.log(`\n=== ALL TASKS FINISHED IN {totalTime}ms ===`);

  let succeeded = 0;
  let failed = 0;
  results.forEach(res => {
    if (res.status === "fulfilled") succeeded++;
    else failed++;
  });

  console.log(`Success: {succeeded} / Failed: {failed}`);
  console.log("Sample Result Payload:", results[0]);
}

main();

function validatePayloadBatch(records) {
  if (records.length === 0) return Promise.resolve();
  const item = records.shift();
  return processItem(item).then(() => validatePayloadBatch(records));
}

async function validatePayloadBatchSafe(records) {
  let count = 0;
  for (const item of records) {
    await processItem(item);
    count++;
    if (count % 100 === 0) {
      // Yield to macrotask queue: allows Libuv to process network I/O & health checks!
      await new Promise(resolve => setImmediate(resolve));
    }
  }
}

// CATASTROPHIC WATERFALL
const user = await fetchUserProfile(userId);      // 400ms
const cart = await fetchUserCart(userId);          // 500ms
const discounts = await fetchActiveDiscounts();    // 350ms
const shippingRules = await fetchShippingRules();  // 450ms

const [user, cart, discounts, shippingRules] = await Promise.all([
  fetchUserProfile(userId),
  fetchUserCart(userId),
  fetchActiveDiscounts(),
  fetchShippingRules()
]);

// CATASTROPHIC ASYNC BUG
async function notifyAllUsers(users) {
  users.forEach(async (user) => {
    // forEach does NOT await this promise!
    await sendEmail(user.email);
  });
  console.log("All emails sent!"); // PRINTS IMMEDIATELY BEFORE ANY EMAIL IS SENT!
}

// ANTI-PATTERN: Wrapping already-asynchronous APIs in 'new Promise()'
function fetchUserData(userId) {
  return new Promise((resolve, reject) => {
    fetch(`/api/users/{userId}`)
      .then(res => res.json())
      .then(data => resolve(data))
      .catch(err => reject(err));
  });
}

// CLEAN ARCHITECTURAL IDIOM: Return the promise chain directly!
function fetchUserDataClean(userId) {
  return fetch(`/api/users/{userId}`).then(res => res.json());
}

console.log("1");

setTimeout(() => {
  console.log("2");
  Promise.resolve().then(() => console.log("3"));
}, 0);

new Promise((resolve) => {
  console.log("4");
  resolve();
}).then(() => {
  console.log("5");
  setTimeout(() => console.log("6"), 0);
}).then(() => {
  console.log("7");
});

console.log("8");

async function onboardUser(userId) {
  const idVerification = await verifyIdentity(userId);
  const stripeCustomer = await createStripeCustomer(userId);
  const dbSchema = await provisionDatabaseSchema(userId);
  return { idVerification, stripeCustomer, dbSchema };
}

async function onboardUserOptimized(userId) {
  const [idVerification, stripeCustomer, dbSchema] = await Promise.all([
    verifyIdentity(userId),
    createStripeCustomer(userId),
    provisionDatabaseSchema(userId)
  ]);
  return { idVerification, stripeCustomer, dbSchema };
}

function promiseAllSettled(promises) {
  // Coerce input into array to handle non-array iterables
  const items = Array.from(promises);
  
  if (items.length === 0) {
    return Promise.resolve([]);
  }

  // Wrap every item so that it ALWAYS resolves into a diagnostic descriptor object
  const wrappedPromises = items.map(item => {
    return Promise.resolve(item)
      .then(value => ({
        status: "fulfilled",
        value: value
      }))
      .catch(reason => ({
        status: "rejected",
        reason: reason
      }));
  });

  // Because all wrapped promises are guaranteed to fulfill, Promise.all will never reject!
  return Promise.all(wrappedPromises);
}

// Verification Harness
const p1 = Promise.resolve("Data 1");
const p2 = Promise.reject(new Error("Network timeout"));
const p3 = 100; // Plain non-promise value

promiseAllSettled([p1, p2, p3]).then(results => {
  console.log("allSettled Results:", results);
  // Results:
  // [
  //   { status: 'fulfilled', value: 'Data 1' },
  //   { status: 'rejected', reason: Error: Network timeout },
  //   { status: 'fulfilled', value: 100 }
  // ]
});

async function processBinaryChunks(chunks, signal) {
  const processedResults = [];

  for (let i = 0; i < chunks.length; i++) {
    // 1. Cooperative cancellation check before each chunk
    if (signal.aborted) {
      throw new DOMException("Operation aborted by client", "AbortError");
    }

    // 2. Process chunk
    const chunk = chunks[i];
    const checksum = await computeHashChunk(chunk);
    processedResults.push({ chunkIndex: i, checksum });

    // 3. Yield to Event Loop every 50 chunks
    if (i % 50 === 0) {
      await new Promise((resolve, reject) => {
        const timer = setTimeout(resolve, 0);
        
        // Listen for abort during sleep
        signal.addEventListener("abort", () => {
          clearTimeout(timer);
          reject(new DOMException("Operation aborted by client", "AbortError"));
        }, { once: true });
      });
    }
  }

  return processedResults;
}

// Mock hash function
function computeHashChunk(chunk) {
  return Promise.resolve(chunk.length * 31);
}

// Verification Harness
const controller = new AbortController();
const mockChunks = new Array(500).fill("data_block");

// Trigger abort after 10ms
setTimeout(() => {
  console.log("--> Triggering cancellation signal!");
  controller.abort();
}, 10);

processBinaryChunks(mockChunks, controller.signal)
  .then(res => console.log("Completed chunks:", res.length))
  .catch(err => {
    if (err.name === "AbortError") {
      console.log("Caught expected cooperative AbortError:", err.message);
    } else {
      console.error("Unexpected error:", err);
    }
  });