@bluelibs/runner 4.8.5 → 4.9.0

package/AI.md

@@ -15,6 +15,8 @@
     - [Async Context](#async-context)
     - [Errors](#errors)
   - [HTTP \& Tunnels](#http--tunnels)
+    - [HTTP Client Factory (Recommended)](#http-client-factory-recommended)
+    - [Direct Client Creation (Legacy)](#direct-client-creation-legacy)
   - [Serialization](#serialization)
   - [Testing](#testing)
   - [Observability \& Debugging](#observability--debugging)
@@ -151,6 +153,12 @@ const sendWelcomeEmail = r
 - Use `.on(onAnyOf(...))` to listen to several events while keeping inference.
 - Hooks can set `.order(priority)`; lower numbers run first. Call `event.stopPropagation()` inside `run` to cancel downstream hooks.
 - Wildcard hooks use `.on("*")` and receive every emission except events tagged with `globals.tags.excludeFromGlobalHooks`.
+- Use `.parallel(true)` on event definitions to enable batched parallel execution:
+  - Listeners with the same `order` run concurrently within a batch
+  - Batches execute sequentially in ascending order priority
+  - All listeners in a failing batch run to completion; if multiple fail, an `AggregateError` with all errors is thrown
+  - Propagation is checked between batches only (not mid-batch since parallel listeners can't be stopped mid-flight)
+  - If any listener throws, subsequent batches will not run
 
 ### Middleware
 

package/README.md

@@ -467,7 +467,42 @@ const emergencyHandler = r
   .build();
 ```
 
-> **runtime:** "'A really good office messenger.' That’s me in rollerblades. You launch a 'userRegistered' flare and I sprint across the building, high‑fiving hooks and dodging middleware. `stopPropagation` is you sweeping my legs mid‑stride. Rude. Effective. Slightly thrilling."
+> **runtime:** "'A really good office messenger.' That's me in rollerblades. You launch a 'userRegistered' flare and I sprint across the building, high-fiving hooks and dodging middleware. `stopPropagation` is you sweeping my legs mid-stride. Rude. Effective. Slightly thrilling."
+
+#### Parallel Event Execution
+
+When an event fan-out needs more throughput, mark it as parallel to run same-priority listeners concurrently while preserving priority boundaries:
+
+```typescript
+const parallelEvent = r.event("app.events.parallel").parallel(true).build();
+
+r.hook("app.hooks.first")
+  .on(parallelEvent)
+  .order(0)
+  .run(async (event) => {
+    await doWork(event.data);
+  })
+  .build();
+
+r.hook("app.hooks.second")
+  .on(parallelEvent)
+  .order(0)
+  .run(async () => log.info("Runs alongside first"))
+  .build();
+
+r.hook("app.hooks.after")
+  .on(parallelEvent)
+  .order(1) // Waits for order 0 batch to complete
+  .run(async () => followUp())
+  .build();
+```
+
+**Execution semantics:**
+
+- Listeners sharing the same `order` run concurrently within a batch; batches execute sequentially in ascending order.
+- All listeners in a batch run to completion even if some fail. If multiple listeners throw, an `AggregateError` containing all errors is thrown (or a single error if only one fails).
+- If any listener in a batch throws, later batches are skipped.
+- `stopPropagation()` is evaluated **between batches only**. Setting it inside a batch does not cancel peers already executing in that batch since parallel listeners cannot be stopped mid-flight.
 
 ### Middleware
 
@@ -481,8 +516,8 @@ import { r } from "@bluelibs/runner";
 // Task middleware with config
 type AuthMiddlewareConfig = { requiredRole: string };
 const authMiddleware = r.middleware
-  .task("app.middleware.task.auth")
-  .run(async ({ task, next }, _deps, config: AuthMiddlewareConfig) => {
+  .task<AuthMiddlewareConfig>("app.middleware.task.auth")
+  .run(async ({ task, next }, _deps, config) => {
     // Must return the value
     return await next(task.input);
   })
@@ -504,7 +539,7 @@ type AuthInput = { user: { role: string } };
 type AuthOutput = { user: { role: string; verified: boolean } };
 
 const authMiddleware = r.middleware
-  .task("app.middleware.task.auth")
+  .task<AuthConfig>("app.middleware.task.auth")
   .run(async ({ task, next }, _deps, config: AuthConfig) => {
     if ((task.input as AuthInput).user.role !== config.requiredRole) {
       throw new Error("Insufficient permissions");