@thuum/decor

Type-safe function decorator toolkit for aspect-oriented programming — build reusable, composable patterns for observability, resilience, and flow control in TypeScript.

Installation

npm install @thuum/decor
# or
bun add @thuum/decor

Overview

@thuum/decor provides higher-order functions that wrap existing functions with cross-cutting concerns — without modifying the original implementation. It ships the building blocks; users build the patterns.

Decorator Functions

One-shot functions that decorate a specific target function, returning a new version:

• decorate(fn, wrapper) — Decorates a single function with a wrapper, preserving its signature
• transform(fn, transformer) — Transforms a function into a new one with a potentially different signature

Decorator Factories

Produce reusable decorators that can be applied to many compatible functions:

• attempt — Wraps a function in try-catch, returning a Result<T> instead of throwing
• decorator(wrapper) — Creates a reusable, type-safe function decorator with full interception power
• middleware(mw) — Creates a decorator using a middleware pattern with a next() callback
• probe(probeFn) — Creates a decorator for tracing function execution (arguments and results)

The async variants (available at @thuum/decor/async) include all factories above plus:

• scheduler(next) — Creates a decorator that routes every invocation through a scheduling strategy
• continuation(seed?) — Creates a sequential FIFO scheduler for serializing async execution

Features

• 🔍 Observability — Trace, log, and measure function calls without modifying behavior
• 🛡️ Precondition Guards — Prevent execution when contracts are unmet
• 🔄 Lifecycle Hooks — Trigger setup or teardown around execution
• 💪 Resilience — Retry, timeout, circuit-break, and fallback on failure
• ⚡ Flow Control — Throttle, debounce, serialize, and limit concurrency
• 📦 Caching — Memoize and replay results to avoid redundant work
• 🧩 Composability — Stack decorators declaratively, type-safe and zero-dependency

Motivation

The patterns below appear in virtually every production codebase. @thuum/decor provides primitives that make building them trivial — without coupling your business logic to cross-cutting infrastructure.

Core Use Cases

These are the primary reasons @thuum/decor exists.

Observability

See what happens without changing what happens.

Emit structured telemetry around invocation. May wrap in try/catch with rethrow. Never alters behavior or return values.

import { probe } from "@thuum/decor";

// Structured logging — observe arguments and results
const withLogging = (name: string) =>
  probe((...args: unknown[]) => {
    console.log(`[${name}] called with:`, args);
    return (result) => {
      if (result.ok) {
        console.log(`[${name}] returned:`, result.value);
      } else {
        console.error(`[${name}] threw:`, result.error);
      }
    };
  });

const add = withLogging("add")((a: number, b: number) => a + b);
add(2, 3);
// [add] called with: [2, 3]
// [add] returned: 5

import { middleware } from "@thuum/decor";

// Execution timing — measure duration without altering flow
const withTiming = (label: string) =>
  middleware((next) => {
    const start = performance.now();
    next();
    const elapsed = performance.now() - start;
    console.log(`[${label}] ${elapsed.toFixed(2)}ms`);
  });

const compute = withTiming("compute")((x: number) => x * x);
compute(42); // [compute] 0.01ms

import { probe } from "@thuum/decor";

// Call counting — track invocation frequency
const withCounter = (name: string) => {
  let count = 0;
  return probe((..._args: unknown[]) => {
    count++;
    console.log(`[${name}] invocation #${count}`);
  });
};

const greet = withCounter("greet")((name: string) => `Hello, ${name}!`);
greet("Alice"); // [greet] invocation #1
greet("Bob");   // [greet] invocation #2

import { probe } from "@thuum/decor";

// Tracing spans — emit span-like context for distributed tracing
const withTracing = (spanName: string) =>
  probe((...args: unknown[]) => {
    const traceId = crypto.randomUUID();
    console.log(`[trace:${traceId}] → ${spanName}`, args);
    return (result) => {
      if (result.ok) {
        console.log(`[trace:${traceId}] ← ${spanName} OK`);
      } else {
        console.log(`[trace:${traceId}] ← ${spanName} ERROR`, result.error);
      }
    };
  });

Precondition Guards

Prevent execution when a contract is unmet.

Short-circuit with a throw or early return. Guards protect invariants — they do not produce Result<T>.

import { decorator } from "@thuum/decor";

// Disposed check — prevent use-after-dispose
const guardDisposed = (isDisposed: () => boolean) =>
  decorator((fn, ...args: unknown[]) => {
    if (isDisposed()) {
      throw new Error("Cannot invoke: resource is disposed");
    }
    return fn(...args);
  });

let disposed = false;
const send = guardDisposed(() => disposed)((msg: string) => {
  console.log("Sending:", msg);
});

send("hello"); // Sending: hello
disposed = true;
send("world"); // throws: Cannot invoke: resource is disposed

import { middleware } from "@thuum/decor";

// Already-initialized / idempotency — execute only once
const once = (() => {
  let initialized = false;
  return middleware((next) => {
    if (initialized) return;
    initialized = true;
    next();
  });
})();

const setup = once(() => {
  console.log("Initializing...");
});

setup(); // Initializing...
setup(); // (no-op)

import { decorator } from "@thuum/decor";

// Input validation — reject invalid arguments
const validatePositive = decorator((fn, n: number) => {
  if (n < 0) throw new RangeError(`Expected positive number, got ${n}`);
  return fn(n);
});

const sqrt = validatePositive(Math.sqrt);
sqrt(16);  // 4
sqrt(-1);  // throws RangeError: Expected positive number, got -1

import { decorator } from "@thuum/decor";

// Invariant assertion — fail fast on violated assumptions
const assertNonNull = <T>(label: string) =>
  decorator((fn, value: T | null | undefined) => {
    if (value == null) {
      throw new TypeError(`Invariant violation: ${label} must not be null`);
    }
    return fn(value);
  });

const processUser = assertNonNull<{ name: string }>("user")((user) => {
  return user.name.toUpperCase();
});

processUser({ name: "Alice" }); // "ALICE"
processUser(null);              // throws TypeError

Resilience

Control failure modes declaratively.

Protect against transient and systemic failures. Includes the Result pattern (attempt), retry, timeout, and circuit breaker strategies.

import { attempt } from "@thuum/decor";

// Result pattern — convert throws into values
const divide = (a: number, b: number) => {
  if (b === 0) throw new Error("Divide by zero");
  return a / b;
};

const safeDivide = attempt(divide);
const result = safeDivide(10, 0);

if (!result.ok) {
  console.error("Failed:", result.error); // Failed: Error: Divide by zero
} else {
  console.log("Result:", result.value);
}

import { decorator } from "@thuum/decor/async";

// Retry with exponential backoff — rethrows on exhaustion
const withRetry = (maxAttempts: number, baseDelayMs: number) =>
  decorator(async (fn, ...args: unknown[]) => {
    let lastError: unknown;
    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
      try {
        return await fn(...args);
      } catch (error) {
        lastError = error;
        if (attempt < maxAttempts) {
          const delay = baseDelayMs * Math.pow(2, attempt - 1);
          await new Promise((r) => setTimeout(r, delay));
        }
      }
    }
    throw lastError;
  });

const fetchUser = withRetry(3, 500)(async (id: number) => {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
});

await fetchUser(1); // retries up to 3 times with 500ms, 1000ms, 2000ms delays

import { decorator } from "@thuum/decor/async";

// Timeout — reject after deadline
const withTimeout = (ms: number) =>
  decorator(async (fn, ...args: unknown[]) => {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), ms);
    try {
      return await fn(...args);
    } finally {
      clearTimeout(timeout);
    }
  });

const fetchData = withTimeout(5000)(async (url: string) => {
  const res = await fetch(url);
  return res.json();
});

import { decorator } from "@thuum/decor/async";

// Circuit breaker — fast-fail after threshold
const withCircuitBreaker = (threshold: number, cooldownMs: number) => {
  let failures = 0;
  let openUntil = 0;

  return decorator(async (fn, ...args: unknown[]) => {
    if (Date.now() < openUntil) {
      throw new Error("Circuit is open — request rejected");
    }
    try {
      const result = await fn(...args);
      failures = 0;
      return result;
    } catch (error) {
      failures++;
      if (failures >= threshold) {
        openUntil = Date.now() + cooldownMs;
      }
      throw error;
    }
  });
};

Recipes

High-value patterns that demonstrate @thuum/decor's expressiveness.

Lifecycle Hooks

Trigger setup or teardown around execution.

import { middleware } from "@thuum/decor/async";

// Ensure-initialized — lazily initialize a resource before first use
const ensureInitialized = (init: () => Promise<void>) => {
  let initialized = false;
  return middleware(async (next) => {
    if (!initialized) {
      await init();
      initialized = true;
    }
    await next();
  });
};

const withDb = ensureInitialized(async () => {
  console.log("Connecting to database...");
  await connectToDatabase();
});

const query = withDb(async (sql: string) => {
  return db.execute(sql);
});

await query("SELECT 1"); // Connecting to database... (first call only)
await query("SELECT 2"); // (already initialized)

import { middleware } from "@thuum/decor";

// Before/after hooks — resource acquire/release
const withHooks = (before: () => void, after: () => void) =>
  middleware((next) => {
    before();
    try {
      next();
    } finally {
      after();
    }
  });

const withTransaction = withHooks(
  () => console.log("BEGIN"),
  () => console.log("COMMIT"),
);

const save = withTransaction((data: string) => {
  console.log("Saving:", data);
});

save("record");
// BEGIN
// Saving: record
// COMMIT

Flow Control

Govern when and how often execution happens.

import { decorator } from "@thuum/decor";

// Throttle — limit invocation rate (browser events)
const throttle = (limitMs: number) => {
  let lastCall = 0;
  return decorator((fn, ...args: unknown[]) => {
    const now = Date.now();
    if (now - lastCall < limitMs) return undefined as ReturnType<typeof fn>;
    lastCall = now;
    return fn(...args);
  });
};

const onScroll = throttle(100)((e: Event) => {
  console.log("Scroll event processed");
});

import { decorator } from "@thuum/decor";

// Debounce — delay until activity settles (browser events)
const debounce = (waitMs: number) => {
  let timer: ReturnType<typeof setTimeout> | null = null;
  return decorator((fn, ...args: unknown[]) => {
    if (timer) clearTimeout(timer);
    timer = setTimeout(() => fn(...args), waitMs);
    return undefined as ReturnType<typeof fn>;
  });
};

const onInput = debounce(300)((value: string) => {
  console.log("Search:", value);
});

import { scheduler, continuation } from "@thuum/decor/async";

// Serialization (FIFO) — ensure sequential execution
const next = continuation();
const sequential = scheduler(next);

const process = sequential(async (id: string) => {
  await new Promise((r) => setTimeout(r, Math.random() * 50));
  return `${id} done`;
});

// Calls execute one-at-a-time, in FIFO order
const results = await Promise.all(["a", "b", "c"].map(process));
// ["a done", "b done", "c done"]

Caching

Avoid redundant computation or I/O.

import { decorator } from "@thuum/decor";

// Memoization — cache results by arguments
const memoize = () => {
  const cache = new Map<string, unknown>();
  return decorator((fn, ...args: unknown[]) => {
    const key = JSON.stringify(args);
    if (cache.has(key)) return cache.get(key) as ReturnType<typeof fn>;
    const result = fn(...args);
    cache.set(key, result);
    return result;
  });
};

const fibonacci = memoize()((n: number): number => {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
});

fibonacci(50); // instant

import { decorator } from "@thuum/decor/async";

// TTL cache — expire results after a duration
const withTTLCache = (ttlMs: number) => {
  const cache = new Map<string, { value: unknown; expires: number }>();
  return decorator(async (fn, ...args: unknown[]) => {
    const key = JSON.stringify(args);
    const cached = cache.get(key);
    if (cached && Date.now() < cached.expires) {
      return cached.value as ReturnType<typeof fn>;
    }
    const result = await fn(...args);
    cache.set(key, { value: result, expires: Date.now() + ttlMs });
    return result;
  });
};

const fetchUser = withTTLCache(60_000)(async (id: number) => {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
});

Composability

All decorators produced by @thuum/decor are regular functions — compose them by stacking. The outermost decorator runs first.

import { decorator } from "@thuum/decor/async";
import { probe } from "@thuum/decor/async";

const withLogging = (name: string) =>
  probe((...args: unknown[]) => {
    console.log(`[${name}] →`, args);
    return (result) => {
      if (result.ok) console.log(`[${name}] ←`, result.value);
      else console.error(`[${name}] ✗`, result.error);
    };
  });

const withRetry = (attempts: number) =>
  decorator(async (fn, ...args: unknown[]) => {
    let lastError: unknown;
    for (let i = 1; i <= attempts; i++) {
      try { return await fn(...args); }
      catch (e) { lastError = e; }
    }
    throw lastError;
  });

const withTimeout = (ms: number) =>
  decorator(async (fn, ...args: unknown[]) => {
    const ctrl = new AbortController();
    const t = setTimeout(() => ctrl.abort(), ms);
    try { return await fn(...args); }
    finally { clearTimeout(t); }
  });

// Stack: logging (outermost) → retry → timeout → target
const fetchUser = withLogging("fetchUser")(
  withRetry(3)(
    withTimeout(5000)(async (id: number) => {
      const res = await fetch(`/api/users/${id}`);
      return res.json();
    })
  )
);

await fetchUser(42);
// [fetchUser] → [42]
// (retries with timeout on each attempt)
// [fetchUser] ← { id: 42, name: "Alice" }

Choosing a Decorator

The package offers four functions with full or partial interception power — decorate, decorator, middleware, and probe — at different levels of reusability and control.

Capability Comparison

| Capability | decorate | decorator | middleware | probe | |---|:---:|:---:|:---:|:---:| | Read arguments | ✅ receives ...args | ✅ receives ...args | ❌ only receives next | ✅ receives ...args | | Modify arguments | ✅ can pass different values to fn() | ✅ can pass different values to fn() | ❌ no access | ❌ target always called with original args | | Read return value | ✅ captures fn() result | ✅ captures fn() result | ❌ no access | ✅ via Result<T> callback (read-only) | | Modify return value | ✅ can return something else | ✅ can return something else | ❌ no access | ❌ original value always returned | | Prevent target execution | ✅ simply don't call fn() | ✅ simply don't call fn() | ✅ simply don't call next() | ⚠️ only by throwing before | | Call target multiple times | ✅ (e.g. retry) | ✅ (e.g. retry) | ✅ can call next() multiple times | ❌ always called exactly once | | Code before target | ✅ | ✅ | ✅ | ✅ | | Code after target | ✅ | ✅ | ✅ | ✅ via optional callback | | Observe errors | ✅ with try/catch around fn() | ✅ with try/catch around fn() | ⚠️ indirectly (next throws) | ✅ via Result { ok: false, error } | | Preserve this binding | ✅ auto-bound | ✅ auto-bound | ✅ auto-applied | ✅ auto-applied | | Composable (stackable) | ⚠️ via nesting decorate() calls | ✅ | ✅ | ✅ | | Type-safe wrapper signature | ✅ typed to target params | ✅ typed to target params | ✅ generic over any target | ✅ typed to probe params | | Reusable across functions | ❌ one-shot, bound to specific fn | ✅ returns a reusable decorator | ✅ returns a reusable decorator | ✅ returns a reusable decorator |

Design Intent

| | decorate | decorator | middleware | probe | |---|---|---|---|---| | Mental model | Ad-hoc wrapping — you decorate one specific function | Decorator factory — you create a reusable wrapper for many functions | Flow control gate — you decide whether to proceed | Passive observer — you watch the function | | Responsibility | You call fn(), you handle the result | You call fn(), you handle the result | You call next() to proceed | The framework calls the target for you | | Power level | 🔴 Maximum | 🔴 Maximum | 🟡 Medium | 🟢 Minimum | | Scope | Single function | Any compatible function | Any function | Any compatible function | | Typical use cases | One-off logging, argument clamping, ad-hoc memoization, quick inline wrapping | Reusable memoization, retry, argument validation/transformation, trampolines, access control | Feature flags, timing, before/after hooks, guards, conditional execution | Logging, tracing, metrics, auditing, assertions |

When to Choose Which

• decorate — You want to wrap one specific function with full interception power. Ideal for ad-hoc, inline decoration where the wrapper logic is specific to that function and doesn't need to be reusable.
• probe — You just want to observe without interfering. The target always runs, you optionally inspect the outcome. Ideal for telemetry, logging, and lightweight precondition guards (that throw).
• middleware — You need to control whether the target runs and/or wrap it with before/after logic, but you don't need to touch the arguments or return value. Familiar Express/Koa pattern.
• decorator — You need full control and reusability: create a wrapper once and apply it to many functions. Transform inputs, transform outputs, call the target conditionally or repeatedly, or replace its behavior entirely.

API Reference

decorate(fn, wrapper)

Decorates a single target function with a wrapper, returning a new function with the same signature.

The wrapper receives:

1. fn — the original function (with this already bound)
2. ...args — the arguments passed to the decorated function

It must return the same type as the original function.

import { decorate } from "@thuum/decor";

function greet(name: string) {
  return `Hello, ${name}!`;
}

const loggedGreet = decorate(greet, (fn, name) => {
  console.log(`greet called with "${name}"`);
  const result = fn(name);
  console.log(`greet returned "${result}"`);
  return result;
});

transform(fn, transformer)

Transforms a function into a new one with a potentially different signature (arguments and/or return type).

import { transform } from "@thuum/decor";

const add = (a: number, b: number) => a + b;

const addStrings = transform(add, (fn, a: string, b: string) => {
  return fn(Number(a), Number(b)).toString();
});

addStrings("2", "3"); // "5"

decorator(wrapper)

Creates a reusable, type-safe function decorator. The wrapper receives fn and ...args, and must return the same type as the target.

import { decorator } from "@thuum/decor";

const withLogging = decorator((fn, ...args: unknown[]) => {
  console.log("called with:", args);
  const result = fn(...args);
  console.log("returned:", result);
  return result;
});

const add = withLogging((a: number, b: number) => a + b);
add(2, 3); // logs arguments and result

middleware(mw)

Creates a decorator using a middleware pattern. Call next() to execute the target; skip it to short-circuit.

import { middleware } from "@thuum/decor";

const withGuard = (condition: () => boolean) =>
  middleware((next) => {
    if (!condition()) throw new Error("Guard failed");
    next();
  });

attempt(fn)

Decorates a function so it returns a Result<T> instead of throwing.

import { attempt } from "@thuum/decor";

const safeParse = attempt(JSON.parse);
const result = safeParse("not json");
// { ok: false, error: SyntaxError }

probe(probeFn)

Creates a decorator that observes function execution without interfering. The probeFn receives call arguments and optionally returns a callback that receives the Result<T>.

import { probe } from "@thuum/decor";

const trace = probe((...args: unknown[]) => {
  console.log("→", args);
  return (result) => {
    if (result.ok) console.log("←", result.value);
    else console.error("✗", result.error);
  };
});

Async Variants

All factories have async versions at @thuum/decor/async:

import { decorator, middleware, probe, attempt } from "@thuum/decor/async";
import { scheduler, continuation } from "@thuum/decor/async";

Async factories work identically to their sync counterparts but handle Promise-returning functions and await within wrappers.

scheduler(next) / continuation(seed?)

Async-only. Creates a decorator that routes invocations through a scheduling strategy.

import { scheduler, continuation } from "@thuum/decor/async";

const next = continuation();
const sequential = scheduler(next);

const process = sequential(async (id: string) => {
  await someAsyncWork(id);
  return `${id} done`;
});

// Executes one-at-a-time in FIFO order
await Promise.all(["a", "b", "c"].map(process));

Result<T>

type Result<T> =
  | { ok: true; value: T; error?: never }
  | { ok: false; value?: never; error: unknown };

A discriminated union representing either a successful computation or a failed one. Use result.ok to narrow the type.

License

ISC