@bluelibs/runner 4.5.9 → 4.6.0-alpha

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

@@ -19,8 +19,13 @@ _Or: How I Learned to Stop Worrying and Love Dependency Injection_
 | [Migrate from 3.x.x to 4.x.x](https://github.com/bluelibs/runner/blob/main/readmes/MIGRATION.md)                    | Guide   | Step-by-step upgrade from v3 to v4                            |
 | [Runner Lore](https://github.com/bluelibs/runner/blob/main/readmes)                                                 | Docs    | Design notes, deep dives, and context                         |
 | [Example: Express + OpenAPI + SQLite](https://github.com/bluelibs/runner/tree/main/examples/express-openapi-sqlite) | Example | Full Express + OpenAPI + SQLite demo                          |
-| [Example: Fastify + MikroORM + PostgreSQL](https://github.com/bluelibs/runner/tree/main/examples/fastify-mikroorm)  | Example | Full Fastify + MikroORM + PostgreSQL demo                     |
-| [OpenAI Runner Chatbot](https://chatgpt.com/g/g-68b756abec648191aa43eaa1ea7a7945-runner?model=gpt-5-thinking)       | Chatbot | Ask questions interactively, or feed README.md to your own AI |
+|| [Example: Fastify + MikroORM + PostgreSQL](https://github.com/bluelibs/runner/tree/main/examples/fastify-mikroorm)  | Example | Full Fastify + MikroORM + PostgreSQL demo                     |
+|| [OpenAI Runner Chatbot](https://chatgpt.com/g/g-68b756abec648191aa43eaa1ea7a7945-runner?model=gpt-5-thinking)       | Chatbot | Ask questions interactively, or feed README.md to your own AI |
+
+### Community & Policies
+- Code of Conduct: see [CODE_OF_CONDUCT](./CODE_OF_CONDUCT.md)
+- Contributing: see [CONTRIBUTING](./CONTRIBUTING.md)
+- Security: see [SECURITY](./SECURITY.md)
 
 Welcome to BlueLibs Runner, where we've taken the chaos of modern application architecture and turned it into something that won't make you question your life choices at 3am. This isn't just another framework – it's your new best friend who actually understands that code should be readable, testable, and not require a PhD in abstract nonsense to maintain.
 
@@ -958,6 +963,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 +1370,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 +1594,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