@bluelibs/runner 4.5.5 → 4.5.7

package/AI.md

@@ -11,8 +11,8 @@ npm install @bluelibs/runner
 - Auto‑detects platform at runtime. In browsers, `exit()` is unsupported and throws. Env reads use `globalThis.__ENV__`, `process.env`, or `globalThis.env`.
 
 ```ts
-import { setPlatform, BrowserPlatformAdapter } from "@bluelibs/runner/platform";
-setPlatform(new BrowserPlatformAdapter());
+import { setPlatform, PlatformAdapter } from "@bluelibs/runner/platform";
+setPlatform(new PlatformAdapter("browser"));
 //
 globalThis.__ENV__ = { API_URL: "https://example.test" };
 ```
@@ -184,11 +184,9 @@ import { globals, task } from "@bluelibs/runner";
 
 const critical = task({
   id: "app.tasks.critical",
-  meta: {
-    tags: [
-      globals.tags.debug.with({ logTaskInput: true, logTaskResult: true }),
-    ],
-  },
+  tags: [
+    globals.tags.debug.with({ logTaskInput: true, logTaskOutput: true }),
+  ],
   run: async () => "ok",
 });
 ```
@@ -202,7 +200,7 @@ const logsExtension = resource({
   id: "app.logs",
   dependencies: { logger: globals.resources.logger },
   init: async (_, { logger }) => {
-    logger.info("test", { data }); // "trace", "debug", "info", "warn", "error", "critical"
+    logger.info("test", { example: 123 }); // "trace", "debug", "info", "warn", "error", "critical"
     const sublogger = logger.with({
       source: "app.logs",
       context: {},
@@ -214,6 +212,47 @@ const logsExtension = resource({
 });
 ```
 
+## AWS Lambda
+
+- Cache the runner between warm invocations; do not dispose on each call.
+- Disable shutdown hooks (`shutdownHooks: false`) and enable the error boundary.
+- Provide a request-scoped context per invocation via `createContext`.
+- Parse API Gateway v1/v2 events (handle `requestContext.http.method`/`rawPath` and `httpMethod`/`path`) and base64 bodies.
+- Optionally set `context.callbackWaitsForEmptyEventLoop = false` when using long‑lived connections.
+
+Example outline:
+
+```ts
+// bootstrap.ts
+import { resource, task, run, createContext } from "@bluelibs/runner";
+export const RequestCtx: any = createContext("app.http.request");
+// define resources & tasks...
+let rrPromise: Promise<any> | null = null;
+export async function getRunner() {
+  if (!rrPromise) {
+    rrPromise = run(app, { shutdownHooks: false, errorBoundary: true });
+  }
+  return rrPromise;
+}
+
+// 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 path = event?.rawPath || event?.path || "/";
+  const rawBody = event?.body
+    ? event.isBase64Encoded
+      ? Buffer.from(event.body, "base64").toString("utf8")
+      : event.body
+    : undefined;
+  const body = rawBody ? JSON.parse(rawBody) : undefined;
+
+  return RequestCtx.provide({ requestId: context?.awsRequestId ?? "local", method, path }, async () => {
+    // route and call rr.runTask(...)
+  });
+};
+```
+
 ## Middleware (global or local)
 
 Middleware now supports type contracts with `<Config, Input, Output>` signature:

package/README.md

@@ -19,6 +19,7 @@ _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 |
 
 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.
@@ -94,8 +95,6 @@ const { dispose, getResourceValue, runTask, emitEvent } = await run(app);
 const { dispose } = await run(app, { debug: "verbose" });
 ```
 
-> **runtime:** "'Less lines than Hello World.' Incredible. All you had to do was externalize 90% of the work into `express`, Node, and me. But please, bask in the brevity. I’ll be over here negotiating a peace treaty between your dependency tree and reality."
-
 ### Platform & Async Context
 
 Runner auto-detects the platform and adapts behavior at runtime. The only feature present only in Node.js is the use of `AsyncLocalStorage` for managing async context.
@@ -142,8 +141,6 @@ Look, we get it. You could turn every function into a task, but that's like usin
 
 Think of tasks as the "main characters" in your application story, not every single line of dialogue.
 
-> **runtime:** "'Pure-ish.' Like diet chaos. Zero calories, full aftertaste. You stapled dependencies to a function and called it virtuous. It's fine. I’ll keep the receipts while you roleplay purity with side effects in a trench coat."
-
 ### Resources
 
 Resources are the singletons, the services, configs, and connections that live throughout your app's lifecycle. They initialize once and stick around until cleanup time. They have to be registered (via `register: []`) only once before they can be used.
@@ -235,8 +232,6 @@ const dbResource = resource({
 });
 ```
 
-> **runtime:** "Singletons: global variables with a nicer haircut. You ban globals, then create 'resources' that live forever and hold the keys to everything. At least there's a `dispose()`. I’ll believe you use it when I stop finding zombie sockets haunting the process."
-
 ### Events
 
 Events let different parts of your app talk to each other without tight coupling. It's like having a really good office messenger who never forgets anything.
@@ -579,7 +574,7 @@ const loggedTask = task({
 });
 ```
 
-> **runtime:** "Ah, the onion pattern. A matryoshka doll made of promises. Every peel reveals… another logger. Another tracer. Another 'just a tiny wrapper'. I'll keep unwrapping until we hit the single lonely `return` you were hiding like state secrets."
+> **runtime:** "Ah, the onion pattern. A matryoshka doll made of promises. Every peel reveals… another logger. Another tracer. Another 'just a tiny wrapper'."
 
 ### Tags
 
@@ -3205,6 +3200,7 @@ This is part of the [BlueLibs](https://www.bluelibs.com) ecosystem. We're not tr
 - [GitHub Repository](https://github.com/bluelibs/runner) - ⭐ if you find this useful
 - [Documentation](https://bluelibs.github.io/runner/) - When you need the full details
 - [Issues](https://github.com/bluelibs/runner/issues) - When something breaks (or you want to make it better)
+- [Contributing](./CONTRIBUTING.md) - How to file great issues and PRs
 
 _P.S. - Yes, we know there are 47 other JavaScript frameworks. This one's still different._
 

package/dist/index.cjs

@@ -237,6 +237,211 @@ __export(errors_exports, {
   UnknownItemTypeError: () => UnknownItemTypeError,
   ValidationError: () => ValidationError
 });
+
+// src/platform/index.ts
+function detectEnvironment() {
+  if (typeof window !== "undefined" && typeof document !== "undefined") {
+    return "browser";
+  }
+  if (typeof process !== "undefined" && process.versions && process.versions.node) {
+    return "node";
+  }
+  return "universal";
+}
+__name(detectEnvironment, "detectEnvironment");
+var _PlatformAdapter = class _PlatformAdapter {
+  constructor(env) {
+    this.isInitialized = false;
+    this.nodeALSClass = null;
+    // timers
+    this.setTimeout = globalThis.setTimeout;
+    this.clearTimeout = globalThis.clearTimeout;
+    this.env = env ?? detectEnvironment();
+  }
+  async init() {
+    if (this.env === "node") {
+      {
+        {
+          const mod = __require("async_hooks");
+          this.nodeALSClass = mod.AsyncLocalStorage;
+        }
+      }
+    }
+  }
+  onUncaughtException(handler) {
+    switch (this.env) {
+      case "node": {
+        process.on("uncaughtException", handler);
+        return () => process.off("uncaughtException", handler);
+      }
+      case "browser": {
+        const target = globalThis.window ?? globalThis;
+        const h = /* @__PURE__ */ __name((e) => handler(e?.error ?? e), "h");
+        target.addEventListener?.("error", h);
+        return () => target.removeEventListener?.("error", h);
+      }
+      default: {
+        const tgt = globalThis;
+        if (tgt.addEventListener) {
+          const h = /* @__PURE__ */ __name((e) => handler(e?.error ?? e), "h");
+          tgt.addEventListener("error", h);
+          return () => tgt.removeEventListener("error", h);
+        }
+        return () => {
+        };
+      }
+    }
+  }
+  onUnhandledRejection(handler) {
+    switch (this.env) {
+      case "node": {
+        const h = /* @__PURE__ */ __name((reason) => handler(reason), "h");
+        process.on("unhandledRejection", h);
+        return () => process.off("unhandledRejection", h);
+      }
+      case "browser": {
+        const target = globalThis.window;
+        const wrap = /* @__PURE__ */ __name((e) => handler(e.reason), "wrap");
+        target.addEventListener?.("unhandledrejection", wrap);
+        return () => target.removeEventListener?.("unhandledrejection", wrap);
+      }
+      default: {
+        const tgt = globalThis;
+        if (tgt.addEventListener) {
+          const wrap = /* @__PURE__ */ __name((e) => handler(e.reason ?? e), "wrap");
+          tgt.addEventListener("unhandledrejection", wrap);
+          return () => tgt.removeEventListener("unhandledrejection", wrap);
+        }
+        return () => {
+        };
+      }
+    }
+  }
+  onShutdownSignal(handler) {
+    switch (this.env) {
+      case "node": {
+        process.on("SIGINT", handler);
+        process.on("SIGTERM", handler);
+        return () => {
+          process.off("SIGINT", handler);
+          process.off("SIGTERM", handler);
+        };
+      }
+      case "browser": {
+        const win = window;
+        win.addEventListener?.("beforeunload", handler);
+        return () => {
+          win.removeEventListener?.("beforeunload", handler);
+        };
+      }
+      default: {
+        const tgt = globalThis;
+        const cleanup = [];
+        if (tgt.addEventListener) {
+          tgt.addEventListener("beforeunload", handler);
+          cleanup.push(
+            () => tgt.removeEventListener?.("beforeunload", handler)
+          );
+          const vis = /* @__PURE__ */ __name(() => {
+            const doc = globalThis.document;
+            if (doc && doc.visibilityState === "hidden") handler();
+          }, "vis");
+          tgt.addEventListener("visibilitychange", vis);
+          cleanup.push(
+            () => tgt.removeEventListener?.("visibilitychange", vis)
+          );
+        }
+        if (typeof process !== "undefined" && process.on) {
+          process.on("SIGINT", handler);
+          process.on("SIGTERM", handler);
+          cleanup.push(() => {
+            process.off?.("SIGINT", handler);
+            process.off?.("SIGTERM", handler);
+          });
+        }
+        return () => cleanup.forEach((fn) => fn());
+      }
+    }
+  }
+  exit(code) {
+    switch (this.env) {
+      case "node":
+        process.exit(code);
+        return;
+      default:
+        throw new PlatformUnsupportedFunction("exit");
+    }
+  }
+  getEnv(key) {
+    switch (this.env) {
+      case "node":
+        return process.env[key];
+      default: {
+        const g = globalThis;
+        if (g.__ENV__ && typeof g.__ENV__ === "object") return g.__ENV__[key];
+        if (typeof process !== "undefined" && process.env)
+          return process.env[key];
+        if (g.env && typeof g.env === "object") return g.env[key];
+        return void 0;
+      }
+    }
+  }
+  hasAsyncLocalStorage() {
+    switch (this.env) {
+      case "node":
+        return true;
+      // We'll try native, else polyfill
+      case "browser":
+      default:
+        return false;
+    }
+  }
+  createAsyncLocalStorage() {
+    switch (this.env) {
+      case "node": {
+        let instance;
+        const get = /* @__PURE__ */ __name(() => {
+          if (!instance) {
+            if (!this.nodeALSClass) {
+              throw new PlatformUnsupportedFunction(
+                "createAsyncLocalStorage: Platform not initialized"
+              );
+            }
+            instance = new this.nodeALSClass();
+          }
+          return instance;
+        }, "get");
+        return {
+          getStore: /* @__PURE__ */ __name(() => get().getStore(), "getStore"),
+          run: /* @__PURE__ */ __name((store2, callback) => get().run(store2, callback), "run")
+        };
+      }
+      case "browser":
+      default:
+        return {
+          getStore: /* @__PURE__ */ __name(() => {
+            throw new PlatformUnsupportedFunction("createAsyncLocalStorage");
+          }, "getStore"),
+          run: /* @__PURE__ */ __name(() => {
+            throw new PlatformUnsupportedFunction("createAsyncLocalStorage");
+          }, "run")
+        };
+    }
+  }
+};
+__name(_PlatformAdapter, "PlatformAdapter");
+var PlatformAdapter = _PlatformAdapter;
+var platformInstance = null;
+function getPlatform() {
+  if (!platformInstance) {
+    const env = detectEnvironment();
+    platformInstance = new PlatformAdapter(env);
+  }
+  return platformInstance;
+}
+__name(getPlatform, "getPlatform");
+
+// src/errors.ts
 var _RuntimeError = class _RuntimeError extends Error {
   constructor(message) {
     super(message);
@@ -395,7 +600,7 @@ var EventEmissionCycleError = _EventEmissionCycleError;
 var _PlatformUnsupportedFunction = class _PlatformUnsupportedFunction extends RuntimeError {
   constructor(functionName) {
     super(
-      `Platform function not supported in this environment: ${functionName}`
+      `Platform function not supported in this environment: ${functionName}. Detected platform: ${detectEnvironment()}.`
     );
     this.name = "PlatformUnsupportedFunction";
   }
@@ -693,209 +898,6 @@ function isOptional(definition) {
 }
 __name(isOptional, "isOptional");
 
-// src/platform/index.ts
-function detectEnvironment() {
-  if (typeof window !== "undefined" && typeof document !== "undefined") {
-    return "browser";
-  }
-  if (typeof process !== "undefined" && process.versions && process.versions.node) {
-    return "node";
-  }
-  return "universal";
-}
-__name(detectEnvironment, "detectEnvironment");
-var _PlatformAdapter = class _PlatformAdapter {
-  constructor(env) {
-    this.isInitialized = false;
-    this.nodeALSClass = null;
-    // timers
-    this.setTimeout = globalThis.setTimeout;
-    this.clearTimeout = globalThis.clearTimeout;
-    this.env = env ?? detectEnvironment();
-  }
-  async init() {
-    if (this.env === "node") {
-      {
-        {
-          const mod = __require("async_hooks");
-          this.nodeALSClass = mod.AsyncLocalStorage;
-        }
-      }
-    }
-  }
-  onUncaughtException(handler) {
-    switch (this.env) {
-      case "node": {
-        process.on("uncaughtException", handler);
-        return () => process.off("uncaughtException", handler);
-      }
-      case "browser": {
-        const target = globalThis.window ?? globalThis;
-        const h = /* @__PURE__ */ __name((e) => handler(e?.error ?? e), "h");
-        target.addEventListener?.("error", h);
-        return () => target.removeEventListener?.("error", h);
-      }
-      default: {
-        const tgt = globalThis;
-        if (tgt.addEventListener) {
-          const h = /* @__PURE__ */ __name((e) => handler(e?.error ?? e), "h");
-          tgt.addEventListener("error", h);
-          return () => tgt.removeEventListener("error", h);
-        }
-        return () => {
-        };
-      }
-    }
-  }
-  onUnhandledRejection(handler) {
-    switch (this.env) {
-      case "node": {
-        const h = /* @__PURE__ */ __name((reason) => handler(reason), "h");
-        process.on("unhandledRejection", h);
-        return () => process.off("unhandledRejection", h);
-      }
-      case "browser": {
-        const target = globalThis.window;
-        const wrap = /* @__PURE__ */ __name((e) => handler(e.reason), "wrap");
-        target.addEventListener?.("unhandledrejection", wrap);
-        return () => target.removeEventListener?.("unhandledrejection", wrap);
-      }
-      default: {
-        const tgt = globalThis;
-        if (tgt.addEventListener) {
-          const wrap = /* @__PURE__ */ __name((e) => handler(e.reason ?? e), "wrap");
-          tgt.addEventListener("unhandledrejection", wrap);
-          return () => tgt.removeEventListener("unhandledrejection", wrap);
-        }
-        return () => {
-        };
-      }
-    }
-  }
-  onShutdownSignal(handler) {
-    switch (this.env) {
-      case "node": {
-        process.on("SIGINT", handler);
-        process.on("SIGTERM", handler);
-        return () => {
-          process.off("SIGINT", handler);
-          process.off("SIGTERM", handler);
-        };
-      }
-      case "browser": {
-        const win = window;
-        win.addEventListener?.("beforeunload", handler);
-        return () => {
-          win.removeEventListener?.("beforeunload", handler);
-        };
-      }
-      default: {
-        const tgt = globalThis;
-        const cleanup = [];
-        if (tgt.addEventListener) {
-          tgt.addEventListener("beforeunload", handler);
-          cleanup.push(
-            () => tgt.removeEventListener?.("beforeunload", handler)
-          );
-          const vis = /* @__PURE__ */ __name(() => {
-            const doc = globalThis.document;
-            if (doc && doc.visibilityState === "hidden") handler();
-          }, "vis");
-          tgt.addEventListener("visibilitychange", vis);
-          cleanup.push(
-            () => tgt.removeEventListener?.("visibilitychange", vis)
-          );
-        }
-        if (typeof process !== "undefined" && process.on) {
-          process.on("SIGINT", handler);
-          process.on("SIGTERM", handler);
-          cleanup.push(() => {
-            process.off?.("SIGINT", handler);
-            process.off?.("SIGTERM", handler);
-          });
-        }
-        return () => cleanup.forEach((fn) => fn());
-      }
-    }
-  }
-  exit(code) {
-    switch (this.env) {
-      case "node":
-        process.exit(code);
-        return;
-      default:
-        throw new PlatformUnsupportedFunction("exit");
-    }
-  }
-  getEnv(key) {
-    switch (this.env) {
-      case "node":
-        return process.env[key];
-      default: {
-        const g = globalThis;
-        if (g.__ENV__ && typeof g.__ENV__ === "object") return g.__ENV__[key];
-        if (typeof process !== "undefined" && process.env)
-          return process.env[key];
-        if (g.env && typeof g.env === "object") return g.env[key];
-        return void 0;
-      }
-    }
-  }
-  hasAsyncLocalStorage() {
-    switch (this.env) {
-      case "node":
-        return true;
-      // We'll try native, else polyfill
-      case "browser":
-      default:
-        return false;
-    }
-  }
-  createAsyncLocalStorage() {
-    switch (this.env) {
-      case "node": {
-        let instance;
-        const get = /* @__PURE__ */ __name(() => {
-          if (!instance) {
-            if (!this.nodeALSClass) {
-              throw new PlatformUnsupportedFunction(
-                "createAsyncLocalStorage: Platform not initialized"
-              );
-            }
-            instance = new this.nodeALSClass();
-          }
-          return instance;
-        }, "get");
-        return {
-          getStore: /* @__PURE__ */ __name(() => get().getStore(), "getStore"),
-          run: /* @__PURE__ */ __name((store2, callback) => get().run(store2, callback), "run")
-        };
-      }
-      case "browser":
-      default:
-        return {
-          getStore: /* @__PURE__ */ __name(() => {
-            throw new PlatformUnsupportedFunction("createAsyncLocalStorage");
-          }, "getStore"),
-          run: /* @__PURE__ */ __name(() => {
-            throw new PlatformUnsupportedFunction("createAsyncLocalStorage");
-          }, "run")
-        };
-    }
-  }
-};
-__name(_PlatformAdapter, "PlatformAdapter");
-var PlatformAdapter = _PlatformAdapter;
-var platformInstance = null;
-function getPlatform() {
-  if (!platformInstance) {
-    const env = detectEnvironment();
-    platformInstance = new PlatformAdapter(env);
-  }
-  return platformInstance;
-}
-__name(getPlatform, "getPlatform");
-
 // src/globals/middleware/requireContext.middleware.ts
 var requireContextTaskMiddleware = defineTaskMiddleware({
   id: "globals.middleware.requireContext",