@bluelibs/runner 4.8.1 → 4.8.3

package/AI.md

@@ -50,7 +50,7 @@ const createUser = r
   .dependencies({ logger: globals.resources.logger })
   .inputSchema<{ name: string }>({ parse: (value) => value })
   .resultSchema<{ id: string; name: string }>({ parse: (value) => value })
-  .run(async ({ input }, { logger }) => {
+  .run(async (input, { logger }) => {
     await logger.info(`Creating user ${input.name}`);
     return { id: "user-1", name: input.name };
   })
@@ -104,7 +104,7 @@ const sendEmail = r
     loggingMiddleware.with({ label: "email" }),
     tracingMiddleware,
   ])
-  .run(async ({ input }, { emailer }) => {
+  .run(async (input, { emailer }) => {
     await emailer.send(input);
     return { delivered: true };
   })
@@ -131,9 +131,9 @@ const userRegistered = r
 const registerUser = r
   .task("app.tasks.registerUser")
   .dependencies({ userRegistered, userService })
-  .run(async ({ input }, deps) => {
+  .run(async (input, deps) => {
     const user = await deps.userService.create(input);
-    await deps.userRegistered.emit({ userId: user.id, email: user.email });
+    await deps.userRegistered({ userId: user.id, email: user.email });
     return user;
   })
   .build();
@@ -309,7 +309,46 @@ const root = r
   .build();
 ```
 
-Use the unified HTTP client anywhere:
+### HTTP Client Factory (Recommended)
+
+The `globals.resources.httpClientFactory` automatically injects serializer, error registry, and async contexts from the store:
+
+```ts
+import { r, globals } from "@bluelibs/runner";
+
+const myTask = r
+  .task("app.tasks.callRemote")
+  .dependencies({ clientFactory: globals.resources.httpClientFactory })
+  .run(async (input, { clientFactory }) => {
+    // Client automatically has serializer, errors, and contexts injected
+    const client = clientFactory({
+      baseUrl: process.env.API_URL,
+      auth: { token: process.env.API_TOKEN },
+    });
+
+    return await client.task("remote.task", input);
+  })
+  .build();
+
+// Node streaming clients via Node DI factories
+import { globals as nodeGlobals } from "@bluelibs/runner/node";
+
+const nodeTask = r
+  .task("app.tasks.streamingCall")
+  .dependencies({ smartFactory: nodeGlobals.resources.httpSmartClientFactory })
+  .run(async (input, { smartFactory }) => {
+    const client = smartFactory({
+      baseUrl: process.env.API_URL,
+    });
+    // Supports duplex streams and multipart uploads
+    return await client.task("remote.streaming.task", input);
+  })
+  .build();
+```
+
+### Direct Client Creation (Legacy)
+
+You can also create clients directly without DI (manual serializer/error/context passing):
 
 ```ts
 import { createHttpClient } from "@bluelibs/runner";

package/README.md

@@ -76,7 +76,7 @@ const createUser = r
   .task("app.tasks.createUser")
   .dependencies({ server, logger: globals.resources.logger })
   .inputSchema<{ name: string }>({ parse: (value) => value })
-  .run(async ({ input }, { server, logger }) => {
+  .run(async (input, { server, logger }) => {
     await logger.info(`Creating ${input.name}`);
     return { id: "user-123", name: input.name };
   })
@@ -144,7 +144,7 @@ import { r } from "@bluelibs/runner";
 const sendEmail = r
   .task("app.tasks.sendEmail")
   .dependencies({ emailService, logger })
-  .run(async ({ input }, { emailService, logger }) => {
+  .run(async (input, { emailService, logger }) => {
     await logger.info(`Sending email to ${input.to}`);
     return emailService.send(input);
   })
@@ -280,9 +280,9 @@ const userRegistered = r
 const registerUser = r
   .task("app.tasks.registerUser")
   .dependencies({ userService, userRegistered })
-  .run(async ({ input }, { userService, userRegistered }) => {
+  .run(async (input, { userService, userRegistered }) => {
     const user = await userService.createUser(input);
-    await userRegistered.emit({ userId: user.id, email: user.email });
+    await userRegistered({ userId: user.id, email: user.email });
     return user;
   })
   .build();
@@ -484,14 +484,14 @@ const authMiddleware = r.middleware
   .task("app.middleware.task.auth")
   .run(async ({ task, next }, _deps, config: AuthMiddlewareConfig) => {
     // Must return the value
-    return await next(task.input as any);
+    return await next(task.input);
   })
   .build();
 
 const adminTask = r
   .task("app.tasks.adminOnly")
   .middleware([authMiddleware.with({ requiredRole: "admin" })])
-  .run(async ({ input }: { input: { user: User } }) => "Secret admin data")
+  .run(async (input) => "Secret admin data")
   .build();
 ```
 
@@ -531,7 +531,7 @@ const resourceAuthMiddleware = r.middleware
 const adminTask = r
   .task("app.tasks.adminOnly")
   .middleware([authMiddleware.with({ requiredRole: "admin" })])
-  .run(async ({ input }: { input: { user: { role: string } } }) => ({
+  .run(async (input: { user: { role: string } }) => ({
     user: { role: input.user.role, verified: true },
   }))
   .build();
@@ -573,35 +573,62 @@ Access `eventManager` via `globals.resources.eventManager` if needed.
 
 #### Middleware Type Contracts
 
-Middleware can now enforce type contracts using the `<Config, Input, Output>` signature:
+Middleware can enforce type contracts on the tasks that use them, ensuring data integrity as it flows through the system. This is achieved by defining `Input` and `Output` types within the middleware's implementation.
+
+When a task uses this middleware, its own `run` method must conform to the `Input` and `Output` shapes defined by the middleware contract.
 
 ```typescript
 import { r } from "@bluelibs/runner";
 
-// Middleware that transforms input and output types
-type LogConfig = { includeTimestamp: boolean };
-type LogInput = { data: any };
-type LogOutput = { data: any; logged: boolean };
+// 1. Define the contract types for the middleware.
+type AuthConfig = { requiredRole: string };
+type AuthInput = { user: { role: string } }; // Task's input must have this shape.
+type AuthOutput = { executedBy: { role: string; verified: boolean } }; // Task's output must have this shape.
 
-const loggingMiddleware = r.middleware
-  .task("app.middleware.logging")
-  .run(async ({ task, next }, _deps, config: LogConfig) => {
-    console.log(
-      config.includeTimestamp ? new Date() : "",
-      (task.input as LogInput).data,
-    );
-    const result = (await next(task.input)) as LogOutput;
-    return { ...result, logged: true };
+// 2. Create the middleware using these types in its `run` method.
+const authMiddleware = r.middleware
+  .task<AuthConfig, AuthInput, AuthOutput>("app.middleware.auth")
+  .run(async ({ task, next }, _deps, config) => {
+    const input = task.input;
+    if (input.user.role !== config.requiredRole) {
+      throw new Error("Insufficient permissions");
+    }
+
+    // The task runs, and its result must match AuthOutput.
+    const result = await next(input);
+
+    // The middleware can further transform the output.
+    const output = result;
+    return {
+      ...output,
+      executedBy: {
+        ...output.executedBy,
+        verified: true, // The middleware adds its own data.
+      },
+    };
   })
   .build();
 
-// Tasks using this middleware must conform to the Input/Output types
-const loggedTask = r
-  .task("app.tasks.logged")
-  .middleware([loggingMiddleware.with({ includeTimestamp: true })])
-  .run(async ({ input }: { input: { data: string } }) => ({
-    data: input.data.toUpperCase(),
-  }))
+// 3. Apply the middleware to a task.
+const adminTask = r
+  .task("app.tasks.adminOnly")
+  // If you use multiple middleware with contracts they get combined.
+  .middleware([authMiddleware.with({ requiredRole: "admin" })])
+  // If you use .inputSchema() the input must contain the contract types otherwise you end-up with InputContractViolation error.
+  // The `run` method is now strictly typed by the middleware's contract.
+  // Its input must be `AuthInput`, and its return value must be `AuthOutput`.
+  .run(async (input) => {
+    // `input.user.role` is available and fully typed.
+    console.log(`Task executed by user with role: ${input.user.role}`);
+
+    // Returning a shape that doesn't match AuthOutput will cause a compile-time error.
+    // return { wrong: "shape" }; // This would fail!
+    return {
+      executedBy: {
+        role: input.user.role,
+      },
+    };
+  })
   .build();
 ```
 
@@ -616,20 +643,13 @@ Tags are metadata that can influence system behavior. Unlike meta properties, ta
 ```typescript
 import { r } from "@bluelibs/runner";
 
-// Simple string tags
-const apiTask = r
-  .task("app.tasks.getUserData")
-  .tags(["api", "public", "cacheable"])
-  .run(async ({ input }) => getUserFromDatabase(input as any))
-  .build();
-
 // Structured tags with configuration
 const httpTag = r.tag<{ method: string; path: string }>("http.route").build();
 
 const getUserTask = r
   .task("app.tasks.getUser")
-  .tags(["api", httpTag.with({ method: "GET", path: "/users/:id" })])
-  .run(async ({ input }) => getUserFromDatabase((input as any).id))
+  .tags([httpTag.with({ method: "GET", path: "/users/:id" })])
+  .run(async (input) => getUserFromDatabase(input.id))
   .build();
 ```
 
@@ -655,7 +675,7 @@ const routeRegistration = r
 
       const { method, path } = config;
       server.app[method.toLowerCase()](path, async (req, res) => {
-        const result = await taskDef({ ...req.params, ...req.body } as any);
+        const result = await taskDef({ ...req.params, ...req.body });
         res.json(result);
       });
     });
@@ -732,15 +752,18 @@ const internalEvent = r
 Enforce return value shapes at compile time:
 
 ```typescript
-// Tags that enforce type contracts
+// Tags that enforce type contracts input/output for tasks or config/value for resources
+type InputType = { id: string };
+type OutputType = { name: string };
 const userContract = r
-  .tag<void, void, { name: string }>("contract.user")
+  // void = no config, no need for .with({ ... })
+  .tag<void, InputType, OutputType>("contract.user")
   .build();
 
 const profileTask = r
   .task("app.tasks.getProfile")
   .tags([userContract]) // Must return { name: string }
-  .run(async () => ({ name: "Ada" })) // ✅ Satisfies contract
+  .run(async (input) => ({ name: input.id + "Ada" })) // ✅ Satisfies contract
   .build();
 ```
 
@@ -760,7 +783,7 @@ const userNotFoundError = r
 const getUser = r
   .task("app.tasks.getUser")
   .dependencies({ userNotFoundError })
-  .run(async ({ input }, { userNotFoundError }) => {
+  .run(async (input, { userNotFoundError }) => {
     userNotFoundError.throw({ code: 404, message: `User ${input} not found` });
   })
   .build();
@@ -884,7 +907,7 @@ import { r, run } from "@bluelibs/runner";
 
 const calculatorTask = r
   .task("app.tasks.calculator")
-  .run(async ({ input }: { input: { value: number } }) => {
+  .run(async (input: { value: number }) => {
     console.log("3. Task is running...");
     return { result: input.value + 1 };
   })
@@ -949,7 +972,7 @@ const userRegistration = r
     emailService: emailService.optional(), // Optional - won't fail if missing
     analytics: analyticsService.optional(), // Optional - graceful degradation
   })
-  .run(async ({ input }, { database, emailService, analytics }) => {
+  .run(async (input, { database, emailService, analytics }) => {
     // Create user (required)
     const user = await database.users.create(userData);
 
@@ -1051,12 +1074,13 @@ app = app.build();
 const remoteTasksTunnel = r
   .resource("app.tunnels.http")
   .tags([globals.tags.tunnel])
-  .init(async () => ({
+  .dependencies({ createClient: globals.resource.httpClientFactory })
+  .init(async (_, { createClient }) => ({
     mode: "client", // or "server", or "none", or "both" for emulating network infrastructure
     transport: "http", // the only one supported for now
     // Selectively forward tasks starting with "remote.tasks."
     tasks: (t) => t.id.startsWith("remote.tasks."),
-    client: globals.tunnels.http.createClient({
+    client: createClient({
       url: "http://remote-runner:8080/__runner",
     }),
   }))
@@ -1184,9 +1208,7 @@ import type {
 // Task example
 const add = r
   .task("calc.add")
-  .run(
-    async ({ input }: { input: { a: number; b: number } }) => input.a + input.b,
-  )
+  .run(async (input: { a: number; b: number }) => input.a + input.b)
   .build();
 
 type AddInput = ExtractTaskInput<typeof add>; // { a: number; b: number }
@@ -1245,7 +1267,7 @@ const requestMiddleware = r.middleware
 const handleRequest = r
   .task("app.handleRequest")
   .middleware([requestMiddleware])
-  .run(async ({ input }: { input: { path: string } }) => {
+  .run(async (input: { path: string }) => {
     const request = requestContext.use();
     console.log(`Processing ${input.path} (Request ID: ${request.requestId})`);
     return { success: true, requestId: request.requestId };
@@ -1392,10 +1414,10 @@ const expensiveTask = r
     globals.middleware.task.cache.with({
       // lru-cache options by default
       ttl: 60 * 1000, // Cache for 1 minute
-      keyBuilder: (taskId, input) => `${taskId}-${(input as any).userId}`, // optional key builder
+      keyBuilder: (taskId, input: any) => `${taskId}-${input.userId}`, // optional key builder
     }),
   ])
-  .run(async ({ input }: { input: { userId: string } }) => {
+  .run(async (input: { userId: string }) => {
     // This expensive operation will be cached
     return await doExpensiveCalculation(input.userId);
   })
@@ -1423,7 +1445,7 @@ import { r } from "@bluelibs/runner";
 
 const redisCacheFactory = r
   .task("globals.tasks.cacheFactory") // Same ID as the default task
-  .run(async ({ input }: { input: any }) => new RedisCache(input))
+  .run(async (input: { input: any }) => new RedisCache(input))
   .build();
 
 const app = r
@@ -1468,7 +1490,7 @@ Here are real performance metrics from our comprehensive benchmark suite on an M
 const userTask = r
   .task("user.create")
   .middleware([auth, logging, metrics])
-  .run(async ({ input }) => database.users.create(input as any))
+  .run(async (input) => database.users.create(input))
   .build();
 
 // 1000 executions = ~5ms total time
@@ -1528,7 +1550,7 @@ const database = r
 const expensiveTask = r
   .task("app.performance.expensive")
   .middleware([globals.middleware.cache.with({ ttl: 60000 })])
-  .run(async ({ input }) => {
+  .run(async (input) => {
     // This expensive computation is cached
     return performExpensiveCalculation(input);
   })
@@ -1751,7 +1773,7 @@ The logger accepts rich, structured data that makes debugging actually useful:
 const userTask = r
   .task("app.tasks.user.create")
   .dependencies({ logger: globals.resources.logger })
-  .run(async ({ input }, { logger }) => {
+  .run(async (input, { logger }) => {
     // Basic message
     logger.info("Creating new user");
 
@@ -1759,7 +1781,7 @@ const userTask = r
     logger.info("User creation attempt", {
       source: userTask.id,
       data: {
-        email: (input as any).email,
+        email: input.email,
         registrationSource: "web",
         timestamp: new Date().toISOString(),
       },
@@ -1767,7 +1789,7 @@ const userTask = r
 
     // With error information
     try {
-      const user = await createUser(input as any);
+      const user = await createUser(input);
       logger.info("User created successfully", {
         data: { userId: user.id, email: user.email },
       });
@@ -1775,7 +1797,7 @@ const userTask = r
       logger.error("User creation failed", {
         error,
         data: {
-          attemptedEmail: (input as any).email,
+          attemptedEmail: input.email,
           validationErrors: error.validationErrors,
         },
       });
@@ -2028,9 +2050,9 @@ const criticalTask = r
       logTaskOnError: true,
     }),
   ])
-  .run(async ({ input }) => {
+  .run(async (input) => {
     // This task will have verbose debug logging
-    return await processPayment(input as any);
+    return await processPayment(input);
   })
   .build();
 ```
@@ -2171,7 +2193,7 @@ const sendWelcomeEmail = r
   .meta({
     title: "Send Welcome Email",
     description: "Sends a welcome email to newly registered users",
-  } as any)
+  })
   .dependencies({ emailService })
   .run(async ({ input: userData }, { emailService }) => {
     // Email sending logic
@@ -2211,7 +2233,7 @@ const expensiveApiTask = r
     version: "2.1.0",
     apiVersion: "v2",
     costLevel: "high", // Custom property!
-  } as any)
+  })
   .run(async ({ input: prompt }) => {
     // AI generation logic
   })
@@ -2224,7 +2246,7 @@ const database = r
     healthCheck: "/health/db", // Custom property!
     dependencies: ["postgresql", "connection-pool"],
     scalingPolicy: "auto",
-  } as any)
+  })
   // .init(async () => { /* ... */ })
   .build();
 ```
@@ -2254,7 +2276,7 @@ const testEmailer = override(productionEmailer, {
 // Using spread operator works the same way but does not provide type-safety.
 const testEmailer = r
   .resource("app.emailer")
-  .init(async () => ({} as any))
+  .init(async () => ({}))
   .build();
 
 const app = r
@@ -2291,7 +2313,7 @@ const originalMiddleware = taskMiddleware({
 const overriddenMiddleware = override(originalMiddleware, {
   run: async ({ task, next }) => {
     const result = await next(task?.input);
-    return { wrapped: result } as any;
+    return { wrapped: result };
   },
 });
 
@@ -2420,7 +2442,7 @@ const createUserTask = r
   .inputSchema(userSchema) // Works directly with Zod!
   .run(async ({ input: userData }) => {
     // userData is validated and properly typed
-    return { id: "user-123", ...(userData as any) };
+    return { id: "user-123", ...userData };
   })
   .build();
 
@@ -2719,7 +2741,7 @@ type UserData = z.infer<typeof userSchema>;
 const createUser = r
   .task("app.tasks.createUser.zod")
   .inputSchema(userSchema)
-  .run(async ({ input }: { input: UserData }) => {
+  .run(async (input: { input: UserData }) => {
     // Both runtime validation AND compile-time typing
     return { id: "user-123", ...input };
   })