@http-forge/core 0.4.6 → 0.4.7

package/README.md

@@ -267,6 +267,31 @@ const forge = ForgeContainer.create({ scriptScope: 'isolated' });
 
 Use `'isolated'` when importing Postman collections whose scripts re-declare the same identifiers at multiple levels, which would otherwise throw `Identifier already declared` in shared mode.
 
+#### Async Script Execution (Event-Loop Draining)
+
+Like Postman, scripts do **not** end when their synchronous code returns. After the sync body completes, the core keeps the sandbox alive and drains pending timers (`setTimeout`/`setInterval`) and microtasks (un-awaited `Promise`s), then commits variable scopes — so deferred `pm.globals` / `pm.environment` / `pm.variables` writes are visible to the next request **without** `await`.
+
+```typescript
+// Post-response script — committed for the next request, no await required
+setTimeout(() => pm.globals.set('authToken', generateToken()), 1500);
+```
+
+The drain is bounded by `scripts.timeout` (the `scriptTimeout` SDK option), default **5000 ms**, which caps **both** synchronous CPU time and the async-drain window:
+
+```typescript
+const forge = ForgeContainer.create({ scriptTimeout: 10000 });
+```
+
+| Behavior | Notes |
+|----------|-------|
+| Sandbox kept alive after sync return | Pending timers/microtasks drained before the request advances |
+| Deferred `pm.*` writes committed | Visible to the next request without `await` |
+| Errors in timer/Promise callbacks | Reported as a console error, **non-fatal** — the request/test is not failed |
+| Runaway timers | A never-clearing `setInterval` or infinite timer loop is force-cancelled at the timeout, with a warning |
+| No async work | Returns immediately; draining adds no measurable latency |
+
+**Divergences from Postman:** uses real Node timers with a poll-based wall-clock drain (no exact pending-promise count, so pathological microtask recursion is bounded by the budget rather than a precise idle signal); a single `scripts.timeout` bounds both CPU time and the async window.
+
 ### Environment Management
 
 ```typescript
@@ -431,7 +456,7 @@ interface ForgeContainerOptions {
     
     // Script Settings
     scriptRunner?: IScriptRunner;    // Custom script runner
-    scriptTimeout?: number;          // Script timeout (ms)
+    scriptTimeout?: number;          // Script budget (ms); caps CPU time + async-drain window. Default 5000
     
     // History
     enableHistory?: boolean;         // Enable request history