@bluelibs/runner 4.5.8 → 4.5.10

package/AI.md

@@ -184,9 +184,7 @@ import { globals, task } from "@bluelibs/runner";
 
 const critical = task({
   id: "app.tasks.critical",
-  tags: [
-    globals.tags.debug.with({ logTaskInput: true, logTaskOutput: true }),
-  ],
+  tags: [globals.tags.debug.with({ logTaskInput: true, logTaskOutput: true })],
   run: async () => "ok",
 });
 ```
@@ -203,7 +201,7 @@ const logsExtension = resource({
     logger.info("test", { example: 123 }); // "trace", "debug", "info", "warn", "error", "critical"
     const sublogger = logger.with({
       source: "app.logs",
-      context: {},
+      additionalContext: {},
     });
     logger.onLog((log) => {
       // ship or transform
@@ -238,7 +236,8 @@ export async function getRunner() {
 // handler.ts
 export const handler = async (event: any, context: any) => {
   const rr: any = await getRunner();
-  const method = event?.requestContext?.http?.method ?? event?.httpMethod ?? "GET";
+  const method =
+    event?.requestContext?.http?.method ?? event?.httpMethod ?? "GET";
   const path = event?.rawPath || event?.path || "/";
   const rawBody = event?.body
     ? event.isBase64Encoded
@@ -247,9 +246,12 @@ export const handler = async (event: any, context: any) => {
     : undefined;
   const body = rawBody ? JSON.parse(rawBody) : undefined;
 
-  return RequestCtx.provide({ requestId: context?.awsRequestId ?? "local", method, path }, async () => {
-    // route and call rr.runTask(...)
-  });
+  return RequestCtx.provide(
+    { requestId: context?.awsRequestId ?? "local", method, path },
+    async () => {
+      // route and call rr.runTask(...)
+    },
+  );
 };
 ```
 
@@ -396,6 +398,21 @@ const { dispose } = await run(app, {
 });
 ```
 
+## Type Helpers
+
+Extract generics from tasks, resources, and events without re-declaring their shapes and avoid use of 'any'.
+
+```ts
+import { task, resource, event } from "@bluelibs/runner";
+import type {
+  ExtractTaskInput, // ExtractTaskInput(typeof myTask)
+  ExtractTaskOutput,
+  ExtractResourceConfig,
+  ExtractResourceValue,
+  ExtractEventPayload,
+} from "@bluelibs/runner";
+```
+
 ## Run Options (high‑level)
 
 - debug: "normal" | "verbose" | DebugConfig
@@ -521,115 +538,40 @@ Coverage tip: the script name is `npm run coverage`.
 
 ## Metadata & Tags
 
+Tags and meta can be applied to all elements.
+
 ```ts
 import { tag, globals, task, resource } from "@bluelibs/runner";
 
-// Simple tags and debug/system globals
-const perf = tag<{ warnAboveMs: number }>({ id: "perf" });
 const contractTag = tag<void, void, { result: string }>({ id: "contract" });
-
-const processPayment = task({
-  id: "app.tasks.pay",
-  tags: [perf.with({ warnAboveMs: 1000 })],
-  meta: {
-    title: "Process Payment",
-    description: "Detailed",
-  },
-  run: async () => {
-    /* ... */
-  },
-});
-
-const internalSvc = resource({
-  id: "app.resources.internal",
-  register: [perf],
-  tags: [globals.tags.system],
-  init: async () => ({}),
-});
-```
-
-### Tag Contracts (type‑enforced returns)
-
-```ts
-// Contract enforces the awaited return type (Config, Input, Output)
-const userContract = tag<void, void, { name: string }>({ id: "contract.user" });
-
-const getProfile = task({
-  id: "app.tasks.getProfile",
-  tags: [userContract],
-  run: async () => ({ name: "Ada" }), // must contain { name: string }
+const httpRouteTag = tag<{ method: "GET" | "POST"; path: string }>({
+  id: "httpRoute",
 });
 
-const profileService = resource({
-  id: "app.resources.profile",
-  tags: [userContract],
-  init: async () => ({ name: "Ada" }),
-});
-```
-
-### Tag Extraction (behavior flags)
-
-```ts
-const perf = tag<{ warnAboveMs: number }>({ id: "perf" });
-
-const perfMiddleware = taskMiddleware({
-  id: "app.middleware.perf",
-  run: async ({ task, next }) => {
-    const cfg = perf.extract(task.definition);
-    // use perf.exists(task.definition) to check for existence
-    if (!cfg) return next(task.input);
-    // performance hooks here ...
+const task = task({
+  id: "app.tasks.myTask",
+  tags: [contractTag, httpRouteTag.with({ method: "POST", path: "/do" })],
+  run: async () => ({ result: "ok" }), // must return { result: string }
+  meta: {
+    title: "My Task",
+    description: "Does something important", // multi-line description, markdown
   },
 });
 ```
 
-### Intercept Tasks via Tags (programmatic wiring)
-
-Use a hook on `globals.events.ready` to discover and intercept tasks by tag:
+Usage:
 
 ```ts
-import { hook, globals, tag } from "@bluelibs/runner";
-
-const apiTag = tag<void>({ id: "api" });
-
-const addTracingToApiTasks = hook({
-  id: "app.hooks.traceApis",
+const onReady = hook({
+  id: "app.hooks.onReady",
   on: globals.events.ready,
   dependencies: { store: globals.resources.store },
   run: async (_, { store }) => {
-    const apiTasks = store.getTasksWithTag(apiTag); // tag object or string id
-    apiTasks.forEach((taskDef) => {
-      taskDef.intercept(async (next, input) => {
-        // ...
-      });
-    });
-    // Apply same concept to routing like fastify, express routes based on tag config to your fastify instance.
-  },
-});
-```
-
-### Route registration via tags (ready hook)
-
-```ts
-import { hook, globals } from "@bluelibs/runner";
-import { httpTag } from "./http.tag"; // your structured tag (method, path, schemas, etc.)
-import { expressServer } from "./expressServer"; // resource that returns { app, port }
-
-const registerRoutes = hook({
-  id: "app.hooks.registerRoutes",
-  on: globals.events.ready,
-  dependencies: { store: globals.resources.store, server: expressServer },
-  run: async (_, { store, server }) => {
-    const tasks = store.getTasksWithTag(httpTag);
+    // Same concept for resources
+    const tasks = store.getTasksWithTag(httpRouteTag); // uses httpRouteTag.exists(component);
     tasks.forEach((t) => {
-      const cfg = httpTag.extract(t.meta?.tags || []);
-      if (!cfg?.config) return;
-      const { method, path } = cfg.config;
-      if (!method || !path) return;
-      (server.app as any)[method.toLowerCase()](path, async (req, res) => {
-        const result = await t({ ...req.body, ...req.query, ...req.params });
-        res.json(result);
-      });
+      const cfg = httpRouteTag.extract(tasks); // { method, path }
+      // you can even do t
     });
   },
 });
@@ -704,7 +646,7 @@ interface IValidationSchema<T> {
 }
 ```
 
-Works out of the box with Zod (`z.object(...).parse`), and can be adapted for Yup/Joi with small wrappers.
+Works out of the box with Zod (`z.object(...).parse`), and can be adapted for Yup/Joi with small wrappers. As it only needs a parse() method.
 
 ```ts
 import { z } from "zod";
@@ -728,6 +670,10 @@ event({
   payloadSchema, // Runs on event emission
 });
 
+tag({
+  configSchema, // Tag config validation (runs on .with())
+});
+
 // Middleware config validation (runs on .with())
 middleware({
   // ...

package/README.md

@@ -958,6 +958,43 @@ const handleRequest = resource({
 });
 ```
 
+## Type Helpers
+
+These utility types help you extract the generics from tasks, resources, and events without re-declaring them. Import them from `@bluelibs/runner`.
+
+```ts
+import { task, resource, event } from "@bluelibs/runner";
+import type {
+  ExtractTaskInput,
+  ExtractTaskOutput,
+  ExtractResourceConfig,
+  ExtractResourceValue,
+  ExtractEventPayload,
+} from "@bluelibs/runner";
+
+// Task example
+const add = task({
+  id: "calc.add",
+  run: async (input: { a: number; b: number }) => input.a + input.b,
+});
+
+type AddInput = ExtractTaskInput<typeof add>; // { a: number; b: number }
+type AddOutput = ExtractTaskOutput<typeof add>; // number
+
+// Resource example
+const config = resource({
+  id: "app.config",
+  init: async (cfg: { baseUrl: string }) => ({ baseUrl: cfg.baseUrl }),
+});
+
+type ConfigInput = ExtractResourceConfig<typeof config>; // { baseUrl: string }
+type ConfigValue = ExtractResourceValue<typeof config>; // { baseUrl: string }
+
+// Event example
+const userRegistered = event<{ userId: string; email: string }>({ id: "app.events.userRegistered" });
+type UserRegisteredPayload = ExtractEventPayload<typeof userRegistered>; // { userId: string; email: string }
+```
+
 ### Context with Middleware
 
 Context shines when combined with middleware for request-scoped data:
@@ -1328,7 +1365,7 @@ BlueLibs Runner achieves high performance while providing enterprise features:
 | Event System         | ~0.013ms             | Loose coupling, observability |
 | Middleware Chain     | ~0.0003ms/middleware | Cross-cutting concerns        |
 | Resource Management  | One-time init        | Singleton pattern, lifecycle  |
-| Built-in Caching     | 1.8x speedup         | Automatic optimization        |
+| Built-in Caching     | Variable speedup     | Automatic optimization        |
 
 **Bottom line**: The framework adds minimal overhead (~0.005ms per task) while providing significant architectural benefits.
 
@@ -1552,10 +1589,12 @@ const requestHandler = task({
     const request = RequestContext.use();
 
     // Create a contextual logger with bound metadata with source and context
-    const requestLogger = logger.with("api.handler", {
+    const requestLogger = logger.with({
       source: requestHandler.id,
-      requestId: request.requestId,
-      userId: request.userId,
+      additionalContext: {
+        requestId: request.requestId,
+        userId: request.userId,
+      },
     });
 
     // All logs from this logger will include the bound context

package/dist/index.cjs

@@ -4105,13 +4105,7 @@ async function run(resourceOrResourceWithConfig, options) {
     store2.lock();
     eventManager.lock();
     await logger.lock();
-    await eventManager.emit(
-      globalEvents.ready,
-      {
-        root: store2.root.resource
-      },
-      "system"
-    );
+    await eventManager.emit(globalEvents.ready, void 0, "run");
     await boundedLogger.info("Runner online. Awaiting tasks and events.");
     if (shutdownHooks) {
       unhookShutdown = registerShutdownHook(() => store2.dispose());