Forem: Theodor Diaconu

sandbox individual npm dependencies in your node app

Theodor Diaconu — Fri, 27 Mar 2026 10:52:08 +0000

Node has process permission flags like allowNet, allowFsRead, etc. The catch is that they apply to your entire running app, and we all know dependencies can get... creative.

https://github.com/bluelibs/sandboxify
npm: sandboxify
Current version: 0.0.1

The idea is pretty simple: run selected packages in a separate Node child process with restricted permissions, while keeping your app code relatively normal. Under the hood, it creates RPC-like adapters so you can call into those sandboxed packages without having to redesign your app around workers or a custom RPC layer.

So instead of fully trusting every dependency, you can isolate the ones you’d rather keep on a shorter leash.

It can sandbox:

npm packages (including their dep trees)
local files
even local folders

This feels especially useful for things like PDF generation, HTML sanitizing, parsing, templating, and other workloads where:

the dependency does meaningful work per call
a little process-boundary/RPC overhead is acceptable
reducing the dependency’s permissions is worth it

Performance is definitely the main tradeoff, so I tried to design around that a bit. sandboxify supports batching, and one of the more practical patterns is to move heavier logic into a local file inside the same sandbox bucket so you can export a higher-level function and do fewer cross-process calls. In other words: less chatty RPC, more useful work per hop.

That said, one practical way to reduce the overhead is to move heavier logic into a local file, put that file in the same sandbox bucket, and export a higher-level function from there. That way, instead of doing lots of tiny cross-process calls, you do fewer, heavier ones.

It’s also still early. First-class support is for ESM, and CJS support currently works in a more hacky way. Even so, it already covers a lot of scenarios.

I put together a small example here you can start playing with it:
https://github.com/theodorDiaconu/sandboxify-test

So yeah, this project is still rough around the edges, but I think the model is promising: dependency-level sandboxing in Node, without having to rebuild everything around workers or hand-rolled RPC.

Is this something you’d actually use?
Which dependency types feel like the best fit?
What limitations would be a deal-breaker for you?

If nothing else, this has been a fun excuse to make untrusted code sit at the kids’ table.

durable workflows for agents

Theodor Diaconu — Wed, 25 Mar 2026 12:31:03 +0000

Everyone is building "agent workflow" libraries right now.

Many of them optimize the easiest part.

It is not that hard to wire:

model calls
tool calls
retries
fallback models
structured outputs

Give that task to a strong model and you can get a surprisingly decent orchestration layer very quickly.

I am not saying those abstractions are useless.

I am saying they are usually not the real problem.

The real problem begins when your workflow lasts longer than the HTTP request that created it.

That is where agent systems stop being a prompt-engineering exercise and start becoming a systems problem. The solution is to employ durable workflows from Runner: https://runner.bluelibs.com/guide/durable-workflows

The Real Problem Is Time

Real agent workflows often span minutes, hours, or days.

They wait for:

human approval
revised input
compliance review
a webhook from another system
a scheduled retry window
a sub-workflow to finish somewhere else

And while they wait, life happens:

your server restarts
you deploy a new version
a worker crashes
a queue redelivers
another node picks up the execution
a user wants to cancel the whole thing right now

That is the part many agent libraries underplay.

They help you choreograph the model.
They do not help you survive time.

And sadly, a JavaScript closure is not a distributed systems primitive. It has great vibes, but terrible crash recovery.

Why Durable Workflows Fit Agent Systems So Well

Durable workflows solve the part that actually hurts:

they persist progress
they survive crashes and restarts
they let you wait for outside signals cleanly
they support safe cancellation
they scale horizontally without relying on in-memory timers

This makes them an excellent fit for agent systems, because agent systems are full of pauses, retries, gates, and long-lived state transitions.

You do not adopt durable workflows because your LLM is clever.
You adopt them because your servers are mortal.

The Mental Model

A durable workflow is a normal async function with checkpoints.

In Runner, the workflow does not resume from some frozen JavaScript instruction pointer.

Instead, on recovery or wake-up, it re-runs from the top and fast-forwards through completed steps using persisted results.

The important rule is simple:

Put side effects inside step(). Code outside a durable step may run more than once.

That rule is what prevents "oops, we charged the customer twice" or "great news, we emailed them three times."

And one more practical note: keep step IDs stable for in-flight workflows across deploys.

This mental model feels a bit like useEffect() for the backend, if useEffect() had persistence, signals, a helmet, and significantly better survival instincts.

A Tiny Workflow Example

This is the shape I want from an agent workflow:

// assume Approved is a typed event declared elsewhere
const workflow = r
  .task("publishArticleWorkflow")
  .dependencies({ durable })
  .tags([
    tags.durableWorkflow.with({
      category: "content",
      signals: [Approved],
    }),
  ])
  .run(async (input: { articleId: string }, { durable }) => {
    const d = durable.use();

    await d.step("generate-draft", async () => {
      // call model, save draft, persist metadata
      return { articleId: input.articleId };
    });

    await d.waitForSignal(Approved, { stepId: "wait-approval" });
    await d.sleep(60 * 60 * 1000, { stepId: "cooldown-before-publish" });

    await d.step("publish", async () => {
      // publish once, even across crashes/recovery
      return { ok: true };
    });
  })
  .build();

That is a much better foundation for AI work than "please do not restart this container for the next six hours."

Runner's Durable Workflows

Runner is a backend framework, but its durable workflow capability can be used on its own inside an existing app.

Today, Runner durable workflows live on the Node side via @bluelibs/runner/node.

The setup is intentionally small:

import { r, run } from "@bluelibs/runner";
import { resources, tags } from "@bluelibs/runner/node";

const Approved = r.event<{ approvedBy: string }>("approved").build();

const durable = resources.memoryWorkflow.fork("app-durable");

const workflow = r
  .task("publishArticleWorkflow")
  .dependencies({ durable })
  .tags([
    tags.durableWorkflow.with({
      category: "articles",
      signals: [Approved],
    }),
  ])
  .run(async (input: { articleId: string }, { durable }) => {
    const d = durable.use();

    const result = await d.step("prepare-article", async () => {
      return { articleId: input.articleId, ready: true };
    });

    const approval = await d.waitForSignal(Approved, {
      stepId: "wait-approval",
      timeoutMs: 24 * 60 * 60 * 1000,
    });

    if (approval.kind === "timeout") {
      return { status: "timed_out" as const };
    }

    return await d.step("publish-article", async () => {
      return {
        status: "published" as const,
        approvedBy: approval.payload.approvedBy,
        publishedAt: Date.now(),
      };
    });
  })
  .build();

const app = r
  .resource("app")
  .register([
    resources.durable,
    durable.with({
      queue: { consume: true },
      polling: { enabled: true, interval: 1000 },
      recovery: { onStartup: true },
    }),
    workflow,
    Approved,
  ])
  .build();

const runtime = await run(app);
const durableRuntime = runtime.getResourceValue(durable);

Then you start it:

const executionId = await durableRuntime.start(workflow, {
  articleId: "article-42",
});

And later, from an API route, admin screen, webhook, or another service:

await durableRuntime.signal(executionId, Approved, {
  approvedBy: "editor@company.com",
});

That signal wakes the workflow and it continues from the persisted point.
Not from scratch. Not from memory. From durable state.

Why This Matters for Human-in-the-Loop AI

This is the part I really like.

A lot of "AI workflows" are actually:

do some work
pause
wait for a human or another system
continue safely

Runner models that cleanly with typed signals.

In the agent-orchestration example, the workflow can:

create an initial draft
wait for a review decision
handle approve vs revise
wait for a revised draft
publish only inside a durable step

That means the workflow can survive real editorial loops instead of only looking impressive in a single uninterrupted demo.

Replay Is the Secret Sauce

The most important concept to understand is replay.

If your process crashes while the workflow is sleeping, waiting for approval, or simply sitting in the queue, recovery does not mean "run everything again and hope for the best."

It means:

completed steps return cached results
waits remain satisfied once their signal is stored
sleeps continue from persisted timers
new work executes only from the next unfinished checkpoint

This is what makes durable workflows fe el safe.

Without replay, long-lived workflows eventually turn into a haunted house of ad hoc tables, boolean flags, timer drift, and very nervous engineers.

Cancellation Is Not an Afterthought

Agent systems also need smart cancellation.

Not "we removed it from the UI, good luck everybody."

Runner exposes cancellation directly:

await durableRuntime.cancelExecution(executionId, "User requested");

If a step is currently running, its AbortSignal is triggered.
If the workflow is sleeping or waiting for a signal, cancellation can complete immediately.

That gives you a sane model for:

user-aborted workflows
policy shutdowns
stale executions
operator interventions

Horizontal Scaling Without Fear

This is the other big reason durable workflows fit agent systems.

Once workflows can span real time, you do not want ownership to depend on one process keeping a timer alive in RAM.

Runner's production durable setup uses:

Redis for durable execution state
RabbitMQ for work distribution
polling/recovery for timers and orphaned executions

That split is healthy:

the store makes it correct
the queue makes it fast

Or put differently: pub/sub can be speedy, but storage is where truth goes to pay taxes.

A production-flavored setup looks like this:

const durable = resources.redisWorkflow.fork("content-durable");

const durableRegistration = durable.with({
  redis: { url: process.env.REDIS_URL! },
  queue: {
    url: process.env.RABBITMQ_URL!,
    consume: true,
    quorum: true,
  },
  polling: { enabled: true, interval: 1000, concurrency: 10 },
  recovery: { onStartup: true },
});

This gives you a workflow model that can survive deploys, recover orphaned executions, and scale across workers without duplicating side effects.

What Durable Workflows Buy You for AI Systems

If you are building AI systems that involve any of the following:

human approval
review and revision loops
long-running research
multi-step tool execution
scheduled follow-ups
compliance gates
child workflows

then durable workflows are probably a better primitive than another layer of clever prompt choreography.

The hard part is rarely "how do I call the model?"

The hard part is:

how do I pause safely?
how do I resume safely?
how do I avoid doing the same side effect twice?
how do I cancel safely?
how do I scale safely?

Durable workflows answer those questions directly.

Final Thought

I think a lot of the market is solving the shiny part of agent orchestration.

The serious part is persistence, replay, signaling, cancellation, and scale.

That is why durable workflows feel like such a natural fit for agent systems.

Not because they make your prompts smarter.
Because they make your workflows harder to kill.

And in production, that is a very beautiful quality.

Take a look at this simple example to better understand the capability:

https://github.com/bluelibs/runner/tree/main/examples/agent-orchestration

shipping AI skills through npm

Theodor Diaconu — Mon, 23 Mar 2026 15:10:31 +0000

If you're building workflows around AGENTS.md, SKILL.md, Codex-style agents, or team-specific AI playbooks, you've probably run into the same awkward gap:

we have a decent format for skills, but not a great way to distribute them.

Copy-pasting skill folders between repos does not scale. Git submodules are rarely the answer people hope they are. Internal prompts, references, templates, and checklists drift across repos until nobody is quite sure which version is the real one.

That is the problem npm-skills is solving.

It lets npm packages ship AI skills as normal package contents, version them with package.json, distribute them through ordinary registries, and extract them into the workspace where they are actually used.

In short: your AI skills start behaving more like code.

Why this matters

There is already strong momentum around filesystem-based AI conventions:

SKILL.md-based skill folders
AGENTS.md-style repositories
ecosystems like skills.sh

These conventions are powerful because they stay simple. A skill is just a directory. If it contains SKILL.md, it is a skill root. Support files live beside it. No database. No opaque platform.

But teams still need a clean answer to practical questions:

How do we version skills?
How do we share them between projects?
How do we keep private skills inside normal engineering workflows?
How do we pull only the skills we want into a repo-local .agents/skills directory?

npm-skills takes the conventions people already like and gives them a distribution model that fits naturally into the JavaScript ecosystem.

The core idea

Package authors can publish skills inside an npm package, usually under skills/.

Consumers can then run one command:

npm-skills extract

That command scans installed packages, finds directories containing SKILL.md, and copies them into the local project, usually under:

.agents/skills/

So instead of manually copying prompts and references around, teams can install a package and extract the skills that came with it.

What stands out

1. Discovery is predictable

Skill discovery stays intentionally boring:

scan under a configured source folder
treat any directory containing SKILL.md as a skill root
copy that directory recursively as-is

That is exactly the sort of rule you want in tooling like this. It is easy to explain, easy to debug, and easy to trust.

2. It fits existing npm workflows

Skills move through tools teams already use:

package.json
npm versions
private registries
monorepos
install hooks

That means AI skills can travel with the codebases and release processes that already exist in your team.

3. It is conservative about overwrites

This part matters.

npm-skills tries to keep extracted content in sync without treating the whole output directory as disposable.

If an extracted skill destination already exists, it does not silently replace it. In interactive mode it can ask, in non-interactive mode it can skip and warn, and if you want a full replacement you opt into that with --override.

At the same time, full syncs can clean up stale folders left behind by earlier package extractions. That is the useful part: if a package stops shipping a skill, you do not want old extracted leftovers hanging around forever.

The important nuance is that this cleanup is scoped to extracted package content, not unrelated folders in the output directory. So your own local skills can still live alongside extracted ones without being treated as throwaway sync artifacts, but it's better to keep your extracted skills under .gitignore to avoid confusion.

4. It keeps authored and extracted skills easy to separate

Recommended pattern for dealing with local authored skills and extracted ones:

.agents/
  skills/
    my-local-skill/
      SKILL.md
    extracted/
      .gitignore // Ignore the whole extracted folder
      shared-skill/

Now in your package.json file just add:

{
  "npmSkills": {
    "consume": {
      "output": ".agents/skills/extracted"
    }
  }
}

That gives imported skills their own lane and keeps local skills easier to curate.

Quick start

Install it:

npm install npm-skills

Extract skills from dependencies:

npm-skills extract

Or add a script:

{
  "scripts": {
    "skills:extract": "npm-skills extract"
  }
}

If you want extraction to happen after installs:

{
  "scripts": {
    "postinstall": "npm-skills extract --skip-production --override"
  }
}

That --skip-production will not trigger extraction when Node, Deno or Bun's env mode is production

A concrete example of the `refs` API

One of the more interesting parts of npm-skills is the refs workflow. This is for package authors who want to keep canonical docs in one place, but still expose them inside published skills.

Imagine your repo looks like this:

readmes/
  release-process.md
  oncall-guide.md
.agents/
  skills/
    runner/
      release-notes/
        SKILL.md
        references/

During development, you may want release-notes to reference the shared docs from readmes/ instead of duplicating them.

Your package.json can define:

{
  "scripts": {
    "prepack": "npm-skills refs materialize",
    "postpack": "npm-skills refs restore"
  },
  "npmSkills": {
    "publish": {
      "source": ".agents/skills",
      "refs": [
        {
          "source": "readmes",
          "destination": "skills/runner/release-notes/references/readmes"
        }
      ]
    }
  }
}

Here is what that means:

while developing, npm-skills refs restore makes skills/runner/release-notes/references/readmes point back to the real readmes/ folder
right before packing or publishing, npm-skills refs materialize replaces that reference with copied files
after packing, npm-skills refs restore puts the symlink-style setup back

Programmatically, the same flow looks like this:

import { syncSkillPublishRefs } from "npm-skills";

await syncSkillPublishRefs({
  cwd: process.cwd(),
  mode: "materialize",
});

// publish or pack here

await syncSkillPublishRefs({
  cwd: process.cwd(),
  mode: "restore",
});

That is a very practical pattern for repos that want one canonical docs source during development, but real files inside the published package tarball.

It is not just an extraction tool

npm-skills also supports authoring:

npm-skills new <skill-name> scaffolds a new skill
npm-skills refs materialize prepares publishable reference files
npm-skills refs restore restores the development setup after packing

So the project is not only about consuming skills. It is also about making the authoring and publishing side more maintainable.

Who this is for

This feels especially useful for:

platform teams sharing AI workflows across many repos
companies maintaining internal agent or prompt libraries
monorepos that want AI guidance close to specific packages
open source packages that want to ship agent-friendly instructions beside their tooling

If your team already thinks in terms of reusable AI playbooks, packaging them as npm-distributed skills is a very natural next step.

What I like most about the approach

The best part of npm-skills is that it does not try to force a hosted platform or a special database into the workflow.

It leans on the boring, durable parts of the stack:

directories
package versions
explicit config
predictable copying
local extraction

That makes it easier to adopt and easier to audit. Sometimes the best tooling is the tooling that makes a new workflow feel unsurprising.

npm-skills looks very much like that kind of tool.

Final thoughts

There is a real opportunity right now around standardizing how teams write, share, and maintain AI skills. But for that to work, skills need a dependable distribution story.

npm-skills is a strong answer to that problem.

It gives package authors a convention for publishing skills, and gives consuming teams a clean way to extract those skills into the projects that need them. No magic. Just skill folders, npm packages, and a CLI that does the obvious thing well.

If you're already working with SKILL.md and AGENTS.md conventions, this is worth a serious look.

Docs: https://npm-skills.com

experience report: coding a framework with AI

Theodor Diaconu — Thu, 12 Mar 2026 08:48:19 +0000

I'm Theo. I code out of pure passion for over 2 decades, specialized in webdev.

Building something innovative usually comes down to one of two things: you are creatively combining pre-existing concepts into a new "soup" or you are actually finding entirely new paradigms.

Let's be brutally honest: right now, AI is mediocre at best on designing new ideas, with rare and random sparks of genius. But there is a massive exception. Given a crystal-clear specification, AI possesses super-human implementation capabilities.

Recently, I've been using AI tooling to build a new innovative framework (Runner). I've had incredible successes, spectacular failures, and learned exactly where the limits lie. The framework itself is designed to be the next level of backend structure for large apps, basically, a way to keep chaos on a leash when you have massive feature throughput.

If you are building complex systems with AI, here is the exact workflow, prompt structure, and harsh reality check I use to ship without losing my mind.

I manage the AI's behavior using two specific markdown files in my repository.

The Evolving AGENTS.md

This file dictates how the AI should act.

It started with just one line -> "Be passionate about what you do, be thoughtful, clear and precise."

The "Rule of Two" says if the AI makes a mistake that annoys me more than twice, it becomes a permanent rule in AGENTS.md.

No Yelling -> If a problem persists, I re-iterate the rule in different wording (and different placement) rather than screaming "SUPER IMPORTANT!!!" in all caps.

Context Refueling -> If the token context of a chat reaches > 70%, the AI starts forgetting its personality. I manually re-inject @AGENTS.md into the chat to keep it on track.

catch(exception): When dealing with the high-level development workflow, they are immediately added into AGENTS.md (qa scripts, coverage, working with other agents at the same time in same worktree, etc)

The Dense AI.md

For the framework's mechanics, I created an intentionally minimal, extremely dense documentation (which is now at 7000 tokens) file called AI.md.
Whenever I start a new task, the agent is given this file to read. Even if AGENTS.md specifies it, I still manually attach AI.md to the initial prompt. I've noticed the results are exponentially better when it's shoved right in front of the model.

The 8-Step AI Coding Workflow

You can't just say "build the app." You have to treat the AI like a junior developer who works at lightning speed but lacks architectural foresight. Here is my daily loop:

Exploration: Discuss an idea, find the drawbacks, and align on the vision.
Plan Mode: Craft the architectural plan before writing any code.
Plan Review (Optional): Ask the AI to spawn sub-agents to critique its own plan. (I use it for high-risk, high-complexity only)
Implementation & QA: Execute the plan and demand a full QA pass (I have a single qa script which checks: 100% coverage, lints, strict type-checking).
Implementation Review: Spawn a sub-agent to review the written code specifically for simplification, optimization, and clarity (subagents are important because they remove initial biases).
The Second Opinion (Optional): For (high-risk || high-complexity), I ask completely different AI model to get an outside perspective.
Human Review: I review the code/tests myself, going back and forth with the AI for final micro-adjustments.
Commit: Generate the commit message with AI, review it, and push.

Surviving the "Boring Zone"

When an app/library becomes incredibly complex, you naturally forget the tiniest details of how certain flows work. Instead of jumping between 15 files to reconstruct the logic in my head, I ask the AI to dig it up and present it with clickable file references. It gets me back into the "zone" instantly.

More importantly, AI completely eliminates the soul-crushing cost of low-to-medium cognitive tasks - like massive refactors that span 50+ files. Work like that is boring, dissatisfying, and is exactly what leads to project abandonment (especially in open-source projects with no immediate path to revenue). AI gives you wings right when you would otherwise quit.

Why You Must Be the "Code Janitor"

If you're going to adopt this, you need to be cautious.

AI will confidently lie to you. When you have a streak of 10 AI successes, you tend to blindly trust the 11th. Don't. Always take the output with a grain of salt.

An AI's only goal is to finish the prompt. It will take shortcuts and write non-elegant code to get there. Your job shifts from being just a coder to being a Code Architect and a Code Janitor.

Never let a single AI instance brainstorm alone. Specifically prompt it to: "Spawn 5 sub-agents with different personalities and skillsets to brainstorm this, debate it, and give me a pre-validated report." The quality difference is uncomparable.

AI models have a terrible tendency to over-engineer and over-defend their bad code. Sometimes, all it takes is a simple "Are you sure?" to make them immediately re-assess and admit they were leading you down the wrong path.

The Cognitive Load Paradox

Previously, after a few years in a stack, writing boilerplate code became basically relaxation. You had your plan, you had your todos, you put on some music, and you just typed.

Using AI actually makes the cognitive load harder. You are no longer the typist; you are a rapid-fire reviewer and architect constantly evaluating logic. You can still write code the old-school, relaxing way, but once you realize you can build faster using this workflow, it becomes impossible to go back.

If you have any productivity tricks, I'd love to hear more ways you effectively applied AI to your work.

Bulletproof TypeScript: Enforcing Architectural Contracts

Theodor Diaconu — Wed, 01 Oct 2025 07:39:10 +0000

In the world of TypeScript development, we often face a difficult trade-off. On one side, we have the desire for dynamic, flexible, and metadata-driven architectures. On the other, we have the absolute necessity of static type safety. All too often, the more "magical" and dynamic a framework's features are, the more we have to sacrifice the compile-time guarantees that make TypeScript so powerful. We end up with any types, stringly-typed APIs, and runtime errors that should have been caught during development.

But what if you could have the best of both worlds? What if you could build powerful, self-configuring systems that are also fully type-safe, from configuration to execution?

Enter BlueLibs Runner, a framework designed from the ground up to resolve this conflict. With Runner, you can implement sophisticated architectural patterns that are both incredibly dynamic and rigorously type-checked. Let's explore two of its most powerful features: Middleware and Tags.

Part 1: Middleware with Contracts - Beyond Simple Execution Wrapping

Middleware is a familiar concept for most developers. It’s a clean way to handle cross-cutting concerns like logging, authentication, or caching. But in most frameworks, middleware is a black box where type safety is often an afterthought.

BlueLibs Runner reimagines middleware as a first-class, type-safe citizen by allowing you to define a strict contract—including Config, Input, and Output types—right at the start.

Enforcing a Full I/O Contract

By passing generics directly to the r.middleware.task<Config, Input, Output>() builder, you create a contract that is enforced on the middleware itself and, more importantly, on any task that uses it.

Let's create a middleware that not only checks for a user's role but also guarantees the shape of the data flowing in and out of the task.

import { r } from "@bluelibs/runner";

// 1. Define the "shape" of our middleware's contract
type AuthConfig = { requiredRole: string };
type AuthInput = { user: { role: string } }; // The task's input MUST have this shape
type AuthOutput = { executedBy: { role: string } }; // The task's output MUST have this shape

// 2. Create the middleware, passing the contract types as generics
const strictAuthMiddleware = r.middleware
  .task<AuthConfig, AuthInput, AuthOutput>("app.middleware.strictAuth")
  .run(async ({ task, next }, _deps, config) => {
    // `config` and `task.input` are now fully typed, no casting needed!
    if (task.input.user.role !== config.requiredRole) {
      throw new Error("Insufficient permissions");
    }

    // The task runs, and its result is also typed
    const result = await next(task.input);

    // The middleware can safely interact with the result and enrich it
    return {
      ...result,
      executedBy: {
        ...result.executedBy,
        verified: true, // Middleware adds its own value
      },
    };
  })
  .build();

// 3. Now, let's use this middleware on a task.
const myTask = r
  .task("app.tasks.myTask")
  .middleware([strictAuthMiddleware.with({ requiredRole: "editor" })])
  // The `run` function's signature is now automatically and strictly enforced!
  // `input` is `AuthInput`, and the return value must be `AuthOutput`.
  .run(async (input) => {
    // input.user.role is available and typed!
    console.log(`Running as ${input.user.role}`);

    // If you return the wrong shape, TypeScript will scream at you.
    // return { wrong: "shape" }; // COMPILE-TIME ERROR!

    return {
      executedBy: {
        role: input.user.role,
      },
    };
  })
  .build();

This pattern is incredibly robust. The middleware is self-documenting and acts as a guardian of your application's data integrity, catching errors at compile time, not at 3 AM in production.

Part 2: Tags as Dynamic, Type-Safe Metadata

Tags are another feature that Runner elevates from a simple labeling mechanism to a cornerstone of dynamic, type-safe architecture. In Runner, tags are not just strings; they are rich, structured, and type-safe metadata objects.

Their primary purpose is to allow different parts of your system to discover and interact with each other at runtime without being tightly coupled.

Let's see this in action by building a system that automatically registers HTTP routes from tasks.

import { r, run, globals } from "@bluelibs/runner";
import express from "express"; // Example server

// 1. Define a structured, type-safe tag for HTTP routes.
const httpTag = r
  .tag<{ method: "get" | "post"; path: string }>("http.route")
  .build();

// 2. Create tasks and annotate them with our new tag.
const getUserTask = r
  .task("app.tasks.getUser")
  .tags([httpTag.with({ method: "get", path: "/users/:id" })])
  .run(async (input: { id: string }) => ({ id: input.id, name: "Jane Doe" }))
  .build();

const createUserTask = r
  .task("app.tasks.createUser")
  .tags([httpTag.with({ method: "post", path: "/users" })])
  .run(async (input: { name: string }) => ({
    id: "user-123",
    name: input.name,
  }))
  .build();

// 3. Create a resource that discovers and registers these routes at startup.
const serverResource = r
  .resource("app.server")
  .init(async () => {
    const app = express();
    app.use(express.json());
    const listener = app.listen(3000);
    console.log("Server listening on port 3000");
    return { app, listener };
  })
  .dispose(async ({ listener }) => listener.close())
  .build();

const routeRegistrar = r
  .hook("app.hooks.registerRoutes")
  .on(globals.events.ready) // Run this when the system is ready
  .dependencies({ store: globals.resources.store, server: serverResource })
  .run(async (_event, { store, server }) => {
    // Find all tasks that have our httpTag
    const tasksWithHttpTag = store.getTasksWithTag(httpTag);

    console.log(
      `Found ${tasksWithHttpTag.length} tasks to register as routes.`,
    );

    for (const taskDefinition of tasksWithHttpTag) {
      // Extract the typed configuration from the tag
      const config = httpTag.extract(taskDefinition);
      if (!config) continue;

      const { method, path } = config; // `method` and `path` are fully typed!

      console.log(`Registering ${method.toUpperCase()} ${path}`);

      // Register the route in Express
      server.app[method](path, async (req, res) => {
        try {
          const input = { ...req.params, ...req.body, ...req.query };
          const result = await taskDefinition(input);
          res.json(result);
        } catch (error) {
          res.status(500).json({ error: error.message });
        }
      });
    }
  })
  .build();

// 4. Assemble the app
const app = r
  .resource("app")
  .register([getUserTask, createUserTask, serverResource, routeRegistrar])
  .build();

await run(app);

This is incredibly powerful. Our server has no direct knowledge of the user tasks, yet it can serve them as API endpoints. We can add, remove, or change routes just by modifying task tags, and the entire system reconfigures itself at startup, all with complete type safety.

Part 3: The Ultimate Combination - Tags as Enforceable Contracts

While middleware is perfect for applying logic, sometimes you just want to enforce a shape or a contract without adding any runtime overhead. This is where "Contract Tags" shine. A tag can be defined to carry an Input and Output contract, which is then enforced on any task that uses it.

Imagine you want to standardize how data processing tasks work in your system. You can define a contract tag for it.

import { r } from "@bluelibs/runner";

// Define a tag that enforces both an Input and Output contract.
// The second generic is Input, the third is Output.
const dataProcessorContract = r
  .tag<void, { rawData: string }, { processed: boolean; timestamp: Date }>("contract.dataProcessor")
  .build();

// This task satisfies the contract.
const processDataTask = r
  .task("app.tasks.processData")
  .tags([dataProcessorContract])
  // The `run` method's signature is now enforced by the tag.
  // `input` must be `{ rawData: string }`
  // The return value must be `{ processed: boolean; timestamp: Date }`
  .run(async (input) => {
    console.log("Processing:", input.rawData);
    return {
      processed: true,
      timestamp: new Date(),
    };
  })
  .build();

// This task fails the contract because its `run` signature is wrong.
const invalidTask = r
  .task("app.tasks.invalid")
  .tags([dataProcessorContract])
  // COMPILE-TIME ERROR on the `run` implementation!
  // The inferred type of 'run' is '(input: { wrong: string }) => { processed: boolean; }'
  // which is not assignable to the contract's '(input: { rawData: string }) => { processed: boolean; timestamp: Date }'.
  .run(async (input: { wrong: string }) => {
    return {
      processed: true,
    };
  })
  .build();

This pattern allows you to enforce architectural consistency at a high level. You can guarantee that any component fulfilling a certain role in your system adheres to a specific data contract, just by applying a tag. It's like creating your own custom, type-safe annotations that are deeply integrated into the framework, but with zero runtime footprint.

Conclusion: Build Code That's Both Smart and Safe

BlueLibs Runner proves that you don't have to choose between a dynamic, flexible architecture and a safe, statically-typed one.

Middleware with Contracts transforms middleware from a simple wrapper into a guardian of your data flow, ensuring inputs and outputs are always correct.
Type-Safe Tags turn metadata into a powerful tool for building self-configuring systems that are decoupled, extensible, and safe.
Contract Tags allow you to define and enforce architectural patterns across your entire application at compile time.

By embracing these patterns, you can move beyond basic function-level type safety and start thinking about architectural type safety. You can write code that is not only smart and flexible but also robust and maintainable.

Ready to give it a try? Check out the BlueLibs Runner documentation and see how these powerful patterns can revolutionize your next TypeScript project.

Rethinking TypeScript Architecture: From Classes to Composable Functions

Theodor Diaconu — Tue, 30 Sep 2025 07:34:31 +0000

If you've worked on a large TypeScript backend, you've seen the pattern: a sea of @Injectable() services, each growing to dozens of methods. Business logic gets tangled, constructors fill up with dependencies, and unit testing becomes a heavy ceremony of mocking complex class instances.

This class-based approach, inherited from languages like Java and C#, has served us well. But what if it's not the most natural fit for TypeScript? What if we could build simpler, more testable, and more scalable applications by embracing functions as our core building block?

This isn't about abandoning structure; it's about finding a better one. Let's explore an architecture built on four simple, functional concepts:

DI without the Ceremony: Resources that initialize asynchronously.
Tasks as Primitives: Your business logic as focused, testable functions.
Composable Middleware: Cross-cutting concerns as plug-and-play wrappers.
A Decoupled Event Bus: Side effects handled with clean event listeners.

1. DI Without the Ceremony

Dependency Injection is powerful, but it often comes with boilerplate. Decorators are still an experimental feature, and managing the lifecycle of services (especially with async setup) can be awkward.

Consider the typical async setup in a class-based framework:

// The "Old Way": Constructor + Lifecycle Hook
@Injectable()
export class DatabaseService {
  private connection: Connection;

  constructor(@Inject("CONFIG") private config: Config) {
    // Can't do async work here!
  }

  async onModuleInit() {
    // So you do it here instead.
    this.connection = await connect(this.config.databaseUrl);
  }
}

This splits your setup logic and forces a testing ceremony.

With a functional approach, initialization is a single, async step. We call these shared singletons Resources.

// The "Runner Way": A single async `init` function
const database = r
  .resource("db")
  .dependencies({ config: configResource })
  .init(async (_, { config }) => {
    // Await whatever you need.
    const connection = await connect(config.databaseUrl);
    return connection;
  })
  .build();

Dependencies are explicitly listed, and the init function serves as your async constructor. It's simple, predictable, and easy to test—just call init with mock dependencies.

2. Tasks: Your Business Logic, Focused

Instead of a UserService class with create, update, delete, and get methods, what if each of those was a standalone, composable function? We call these Tasks.

A Task is more than just a function; it's a unit of business logic with declared dependencies, optional input/output schemas, and support for middleware.

// The "Old Way": A method on a service
@Injectable()
export class UserService {
  constructor(private db: DatabaseService, private logger: Logger) {}

  async createUser(data: CreateUserDTO) {
    this.logger.info("Creating user...");
    const user = await this.db.users.create(data);
    return user;
  }
}

Testing this requires instantiating UserService with mocks.

A Task, however, is self-contained.

// The "Runner Way": A standalone, testable Task
const createUser = r
  .task("users.create")
  .dependencies({ db: database, logger })
  .inputSchema(z.object({ name: z.string(), email: z.string() }))
  .run(async (input, { db, logger }) => {
    logger.info(`Creating user: ${input.email}`);
    const user = await db.users.insert(input);
    return user;
  })
  .build();

This is powerful for two reasons:

Clarity: The function's dependencies and input shape are declared upfront. The logic is focused.
Trivial Testing: A task's run method can be tested directly by passing its input and mock dependencies. No container, no TestBed.

// It's just a function call.
const user = await createUser.run(
  { name: "Ada", email: "ada@example.com" },
  { db: mockDatabase, logger: mockLogger },
);

3. Middleware: Isolate Your Cross-Cutting Concerns

Where do you put authentication, caching, logging, or retry logic? In a class-based world, you might use decorators or stuff the logic directly into your service methods. This clutters your business logic.

Middleware allows you to wrap Tasks with these concerns in a clean, composable way.

Let's add authentication and retry logic to our createUser task:

const createUser = r
  .task("users.create")
  .dependencies({ db: database, logger })
  .inputSchema(z.object({ name: z.string(), email: z.string() }))
  // ✨ Just add middleware ✨
  .middleware([
    authMiddleware.with({ requiredRole: "admin" }),
    retryMiddleware.with({ retries: 3 }),
  ])
  .run(async (input, { db, logger }) => {
    // The business logic remains pure.
    logger.info(`Creating user: ${input.email}`);
    const user = await db.users.insert(input);
    return user;
  })
  .build();

The core run function is unchanged. The concerns are layered on top, like an onion. Each piece of middleware is a reusable, focused function that can be applied to any task.

4. The Event Bus: Decouple Your Side Effects

What happens after a user is created? You probably need to send a welcome email, update a sales dashboard, and sync to a CRM.

The wrong way is to pack all of that into the createUser task. This creates tight coupling and makes the task bloated and fragile.

A better way is to emit an Event.

// 1. Define an event
const userCreated = r
  .event("users.created")
  .payloadSchema(z.object({ userId: z.string(), email: z.string() }))
  .build();

// 2. Emit it from your task
const createUser = r
  .task("users.create")
  .dependencies({ db, logger, userCreated }) // Depend on the event
  .run(async (input, { db, logger, userCreated }) => {
    const user = await db.users.insert(input);
    // Fire and forget
    await userCreated({ userId: user.id, email: user.email });
    return user;
  })
  .build();

Now, other parts of your system can react to this event using Hooks without createUser knowing or caring about them.

// 3. React to the event in a separate Hook
const sendWelcomeEmail = r
  .hook("hooks.sendWelcomeEmail")
  .on(userCreated) // Listen for the event
  .dependencies({ emailService })
  .run(async (event, { emailService }) => {
    // The hook has its own dependencies and logic
    await emailService.sendWelcome(event.data.email);
  })
  .build();

This is true decoupling. The sendWelcomeEmail logic can be tested in isolation, and the createUser task has a single, clear responsibility.

Putting It All Together

Here’s how these pieces form a complete, runnable application.

import { r, run, globals } from "@bluelibs/runner";

// --- SHARED RESOURCES ---
const logger = globals.resources.logger;
const database = r
  .resource("db")
  .init(async () => connectToDb())
  .build();
const emailService = r
  .resource("email")
  .init(async () => createEmailer())
  .build();

// --- EVENTS ---
const userCreated = r.event("users.created").payloadSchema(/*...*/).build();

// --- MIDDLEWARE ---
const authMiddleware = r.middleware.task("auth").run(/*...*/).build();

// --- BUSINESS LOGIC (TASKS) ---
const createUser = r
  .task("users.create")
  .dependencies({ db: database, logger, userCreated })
  .middleware([authMiddleware])
  .run(async (input, { db, logger, userCreated }) => {
    const user = await db.users.insert(input);
    await userCreated.emit({ userId: user.id, email: user.email });
    return user;
  })
  .build();

// --- SIDE EFFECTS (HOOKS) ---
const sendWelcomeEmail = r
  .hook("hooks.sendWelcomeEmail")
  .on(userCreated)
  .dependencies({ emailService, logger })
  .run(async (event, { emailService, logger }) => {
    await emailService.sendWelcome(event.data.email);
    logger.info(`Welcome email sent to ${event.data.email}`);
  })
  .build();

// --- APPLICATION ---
const app = r
  .resource("app")
  .register([
    logger,
    database,
    emailService,
    userCreated,
    createUser,
    sendWelcomeEmail,
  ])
  .build();

// Run the application
await run(app);

This architecture is flat, explicit, and composes beautifully. It encourages you to build applications from small, testable, and reusable functions, leading to a codebase that is easier to reason about, maintain, and scale.

Ready to ditch the bloated services? Give a functional approach a try.

Resources:

Async & Type-safe Event Management in JS

Theodor Diaconu — Thu, 02 Dec 2021 09:23:27 +0000

In this article, we'll explore the best ways to handle events with TypeScript or vanilla JS inside any runtime environment. (Browser, Node and Deno)

You can test this library very quickly here, and find the full documentation here.

What makes a good event manager from my perspective:

Asynchronous by default
Type-safe by default
Collision-proof design (events with the same name)
Ability to add, remove listeners
Ability to configure the order of triggering of handlers
Ability to listen globally to all events or group of events.
Isomorphic (works independent of JavaScript runtime environment)
Small in size

Install

npm i -S @bluelibs/core

import { EventManager } from "@bluelibs/core";

const eventManager = new EventManager();

It weighs 8.8kB minified and gzipped, but in reality it's 5.28 kB as 30% is reflect-metadata, which is going to be stripped-out most likely by your bundler on the frontend.

Asynchronous

The very definition of handling events is asynchronous, and now that the world is moving to Promise-based applications, we believe that all event handlers should be async by default.

import { EventManager } from "@bluelibs/core";

class SomethingHappenedEvent extends Event {}

async function init() {
  const eventManager = new EventManager();

  eventManager.addListener(SomethingHappenedEvent, async (e) => {
    // Type-safety for e, e is an instance of SomethingHappenedEvent, automatic type inference
    console.log("I have been emitted");
  });

  // This will await execution all events
  await eventManager.emit(new SomethingHappenedEvent());
}

init();

You can also have events that perform things in the background:

eventManager.addListener(SomethingHappenedEvent, async (e) => {
  emailService.sendEmail(); // simply omit "await" for your async service calls

  // Another approach:

  return new Promise(async (resolve, reject) => {
    resolve();

    // Do sync stuff here
  });
});

You could also control this from the event emission:

// don't await emission
eventManager.emit(new SomethingHappenedEvent());

// await and make it blocking
await eventManager.emit(new SomethingHappenedEvent());

This way you benefit of both worlds, giving you ability to control how listeners behave and also giving you the ability to fire-and-forget the event emission too.

Do keep in mind that your handlers can still be non-async and be run in sync, awaiting a non-async function just means it's executing it.

Type-safe

Events can only be classes, we no longer trust strings, they can collide, they are hard to have them type safe.

If you're using vanilla JavaScript, you won't benefit of autocompletion for this part.

class UserAddedEvent extends Event<{
  userId: string;
}> {
  async validate() {
    // Optional runtime validation before it's dispatched to all listeners
  }
}

eventManager.emit(
  new UserAddedEvent({
    userId: "XXX",
  })
);

Management & Order

I'll just let the code do the talking:

const handler = async function empty(e: UserAddedEvent) {};

eventManager.addListener(UserAddedEvent, handler, {
  // Make it run first
  order: -1000, // Use -Infinity if you're feeling courageous
  filter: (e) => e.data.userId !== "ADMIN", // The listener will only run if the filter returns true.
});

eventManager.removeListener(UserAddedEvent);

Global Listeners

manager.addGlobalListener(async (e: Event) => {
  // Custom logging maybe?
});
// and it's subsequent: removeGlobalListener

You could fine-grain this nicely, and listen to groups of events:

class SecurityEvent extends Event {}
class UserNotAuthorized extends SecurityEvent {}
class UserHackingAttemptEvent extends SecurityEvent {}

manager.addGlobalListener(
  async (e: SecurityEvent) => {
    // Send an email or do something specific
  },
  {
    filter: (e) => e instanceof SecurityEvent,
  }
);

Serializable

To see a fully working example on how we can approach serialization check this out: https://stackblitz.com/edit/typescript-jg9osn?file=serializable.ts

You can easily benefit of storing these events and running them later by employing some simple tacticts for the SerializableEvent class, and fine-tune it to suit your needs.

Timeouts

As you know, the listener class has all the control, if for example, you want to set a timeout (takes too much time to execute, and is blocking others),
then you could implement the following strategy: https://stackblitz.com/edit/typescript-jg9osn?file=timebound.ts

The important part here is that the listener knows how to control the flow, and this can give you super-powers when it comes to controlling async events.

Pluggable in your workflow

This can be easily integrated in your workflow and existing web application, on both frontend, backend, NextJS or React Native apps.