DEV Community: Hong Minhee

Your CLI's completion should know what options you've already typed

Hong Minhee — Tue, 13 Jan 2026 05:02:27 +0000

Consider Git's -C option:

git -C /path/to/repo checkout <TAB>

When you hit Tab, Git completes branch names from /path/to/repo, not your
current directory. The completion is context-aware—it depends on the value of
another option.

Most CLI parsers can't do this. They treat each option in isolation, so
completion for --branch has no way of knowing the --repo value. You end up
with two unpleasant choices: either show completions for all possible branches
across all repositories (useless), or give up on completion entirely for these
options.

Optique 0.10.0 introduces a dependency system that solves this problem while
preserving full type safety.

Static dependencies with `or()`

Optique already handles certain kinds of dependent options via the or()
combinator:

import { flag, object, option, or, string } from "@optique/core";

const outputOptions = or(
  object({
    json: flag("--json"),
    pretty: flag("--pretty"),
  }),
  object({
    csv: flag("--csv"),
    delimiter: option("--delimiter", string()),
  }),
);

TypeScript knows that if json is true, you'll have a pretty field, and if
csv is true, you'll have a delimiter field. The parser enforces this at
runtime, and shell completion will suggest --pretty only when --json is
present.

This works well when the valid combinations are known at definition time. But it
can't handle cases where valid values depend on runtime input—like branch
names that vary by repository.

Runtime dependencies

Common scenarios include:

A deployment CLI where --environment affects which services are available
A database tool where --connection affects which tables can be completed
A cloud CLI where --project affects which resources are shown

In each case, you can't know the valid values until you know what the user typed
for the dependency option. Optique 0.10.0 introduces dependency() and
derive() to handle exactly this.

The dependency system

The core idea is simple: mark one option as a dependency source, then create
derived parsers that use its value.

import {
  choice,
  dependency,
  message,
  object,
  option,
  string,
} from "@optique/core";

function getRefsFromRepo(repoPath: string): string[] {
  // In real code, this would read from the Git repository
  return ["main", "develop", "feature/login"];
}

// Mark as a dependency source
const repoParser = dependency(string());

// Create a derived parser
const refParser = repoParser.derive({
  metavar: "REF",
  factory: (repoPath) => {
    const refs = getRefsFromRepo(repoPath);
    return choice(refs);
  },
  defaultValue: () => ".",
});

const parser = object({
  repo: option("--repo", repoParser, {
    description: message`Path to the repository`,
  }),
  ref: option("--ref", refParser, {
    description: message`Git reference`,
  }),
});

The factory function is where the dependency gets resolved. It receives the
actual value the user provided for --repo and returns a parser that validates
against refs from that specific repository.

Under the hood, Optique uses a three-phase parsing strategy:

Parse all options in a first pass, collecting dependency values
Call factory functions with the collected values to create concrete parsers
Re-parse derived options using those dynamically created parsers

This means both validation and completion work correctly—if the user has already
typed --repo /some/path, the --ref completion will show refs from that path.

Repository-aware completion with `@optique/git`

The @optique/git package provides async value parsers that read from Git
repositories. Combined with the dependency system, you can build CLIs with
repository-aware completion:

import {
  command,
  dependency,
  message,
  object,
  option,
  string,
} from "@optique/core";
import { gitBranch } from "@optique/git";

const repoParser = dependency(string());

const branchParser = repoParser.deriveAsync({
  metavar: "BRANCH",
  factory: (repoPath) => gitBranch({ dir: repoPath }),
  defaultValue: () => ".",
});

const checkout = command(
  "checkout",
  object({
    repo: option("--repo", repoParser, {
      description: message`Path to the repository`,
    }),
    branch: option("--branch", branchParser, {
      description: message`Branch to checkout`,
    }),
  }),
);

Now when you type my-cli checkout --repo /path/to/project --branch <TAB>, the
completion will show branches from /path/to/project. The defaultValue of
"." means that if --repo isn't specified, it falls back to the current
directory.

Multiple dependencies

Sometimes a parser needs values from multiple options. The deriveFrom()
function handles this:

import {
  choice,
  dependency,
  deriveFrom,
  message,
  object,
  option,
} from "@optique/core";

function getAvailableServices(env: string, region: string): string[] {
  return [`${env}-api-${region}`, `${env}-web-${region}`];
}

const envParser = dependency(choice(["dev", "staging", "prod"] as const));
const regionParser = dependency(choice(["us-east", "eu-west"] as const));

const serviceParser = deriveFrom({
  dependencies: [envParser, regionParser] as const,
  metavar: "SERVICE",
  factory: (env, region) => {
    const services = getAvailableServices(env, region);
    return choice(services);
  },
  defaultValues: () => ["dev", "us-east"] as const,
});

const parser = object({
  env: option("--env", envParser, {
    description: message`Deployment environment`,
  }),
  region: option("--region", regionParser, {
    description: message`Cloud region`,
  }),
  service: option("--service", serviceParser, {
    description: message`Service to deploy`,
  }),
});

The factory receives values in the same order as the dependency array. If some
dependencies aren't provided, Optique uses the defaultValues.

Async support

Real-world dependency resolution often involves I/O—reading from Git
repositories, querying APIs, accessing databases. Optique provides async
variants for these cases:

import { dependency, string } from "@optique/core";
import { gitBranch } from "@optique/git";

const repoParser = dependency(string());

const branchParser = repoParser.deriveAsync({
  metavar: "BRANCH",
  factory: (repoPath) => gitBranch({ dir: repoPath }),
  defaultValue: () => ".",
});

The @optique/git package uses isomorphic-git under the hood, so gitBranch(),
gitTag(), and gitRef() all work in both Node.js and Deno.

There's also deriveSync() for when you need to be explicit about synchronous
behavior, and deriveFromAsync() for multiple async dependencies.

Wrapping up

The dependency system lets you build CLIs where options are aware of each
other—not just for validation, but for shell completion too. You get type safety
throughout: TypeScript knows the relationship between your dependency sources
and derived parsers, and invalid combinations are caught at compile time.

This is particularly useful for tools that interact with external systems where
the set of valid values isn't known until runtime. Git repositories, cloud
providers, databases, container registries—anywhere the completion choices
depend on context the user has already provided.

This feature will be available in Optique 0.10.0. To try the pre-release:

deno add jsr:@optique/core@0.10.0-dev.311

Or with npm:

npm install @optique/core@0.10.0-dev.311

See the documentation for more details.

Building CLI apps with TypeScript in 2026

Hong Minhee — Tue, 06 Jan 2026 04:27:26 +0000

We've all been there. You start a quick TypeScript CLI with process.argv.slice(2), add a couple of options, and before you know it you're drowning in if/else blocks and parseInt calls. It works, until it doesn't.

In this guide, we'll move from manual argument parsing to a fully type-safe CLI with subcommands, mutually exclusive options, and shell completion.

The naïve approach: parsing `process.argv`

Let's start with the most basic approach. Say we want a greeting program that takes a name and optionally repeats the greeting:

// greet.ts
const args = process.argv.slice(2);

let name: string | undefined;
let count = 1;

for (let i = 0; i < args.length; i++) {
  if (args[i] === "--name" || args[i] === "-n") {
    name = args[++i];
  } else if (args[i] === "--count" || args[i] === "-c") {
    count = parseInt(args[++i], 10);
  }
}

if (!name) {
  console.error("Error: --name is required");
  process.exit(1);
}

for (let i = 0; i < count; i++) {
  console.log(`Hello, ${name}!`);
}

Run node greet.js --name Alice --count 3 and you'll get three greetings.

But this approach is fragile. count could be NaN if someone passes --count foo, and we'd silently proceed. There's no help text. If someone passes --name without a value, we'd read the next option as the name. And the boilerplate grows fast with each new option.

The traditional libraries

You've probably heard of Commander.js and Yargs. They've been around for years and solve the basic problems:

// With Commander.js
import { program } from "commander";

program
  .requiredOption("-n, --name <n>", "Name to greet")
  .option("-c, --count <number>", "Number of times to greet", "1")
  .parse();

const opts = program.opts();

These libraries handle help text, option parsing, and basic validation. But they were designed before TypeScript became mainstream, and the type safety is bolted on rather than built in.

The real problem shows up when you need mutually exclusive options. Say your CLI works either in "server mode" (with --port and --host) or "client mode" (with --url). With these libraries, you end up with a config object where all options are potentially present, and you're left writing runtime checks to ensure the user didn't mix incompatible flags. TypeScript can't help you because the types don't reflect the actual constraints.

Enter Optique

Optique takes a different approach. Instead of configuring options declaratively, you build parsers by composing smaller parsers together. The types flow naturally from this composition, so TypeScript always knows exactly what shape your parsed result will have.

Optique works across JavaScript runtimes: Node.js, Deno, and Bun are all supported. The core parsing logic has no runtime-specific dependencies, so you can even use it in browsers if you need to parse CLI-like arguments in a web context.

Let's rebuild our greeting program:

import { object } from "@optique/core/constructs";
import { option } from "@optique/core/primitives";
import { integer, string } from "@optique/core/valueparser";
import { withDefault } from "@optique/core/modifiers";
import { run } from "@optique/run";

const parser = object({
  name: option("-n", "--name", string()),
  count: withDefault(option("-c", "--count", integer({ min: 1 })), 1),
});

const config = run(parser);
// config is typed as { name: string; count: number }

for (let i = 0; i < config.count; i++) {
  console.log(`Hello, ${config.name}!`);
}

Types are inferred automatically. config.name is string, not string | undefined. config.count is number, guaranteed to be at least 1. Validation is built in: integer({ min: 1 }) rejects non-integers and values below 1 with clear error messages. Help text is generated automatically, and the run() function handles errors and exits with appropriate codes.

Install it with your package manager of choice:

npm add @optique/core @optique/run
# or: pnpm add, yarn add, bun add, deno add jsr:@optique/core jsr:@optique/run

Building up: a file converter

Let's build something more realistic: a file converter that reads from an input file, converts to a specified format, and writes to an output file.

import { object } from "@optique/core/constructs";
import { optional, withDefault } from "@optique/core/modifiers";
import { argument, option } from "@optique/core/primitives";
import { choice, string } from "@optique/core/valueparser";
import { run } from "@optique/run";

const parser = object({
  input: argument(string({ metavar: "INPUT" })),
  output: option("-o", "--output", string({ metavar: "FILE" })),
  format: withDefault(
    option("-f", "--format", choice(["json", "yaml", "toml"])),
    "json"
  ),
  pretty: option("-p", "--pretty"),
  verbose: option("-v", "--verbose"),
});

const config = run(parser, {
  help: "both",
  version: { mode: "both", value: "1.0.0" },
});

// config.input: string
// config.output: string
// config.format: "json" | "yaml" | "toml"
// config.pretty: boolean
// config.verbose: boolean

The type of config.format isn't just string. It's the union "json" | "yaml" | "toml". TypeScript will catch typos like config.format === "josn" at compile time.

The choice() parser is useful for any option with a fixed set of valid values: log levels, output formats, environment names, and so on. You get both runtime validation (invalid values are rejected with helpful error messages) and compile-time checking (TypeScript knows the exact set of possible values).

Mutually exclusive options

Now let's tackle the case that trips up most CLI libraries: mutually exclusive options. Say our tool can either run as a server or connect as a client, but not both:

import { object, or } from "@optique/core/constructs";
import { withDefault } from "@optique/core/modifiers";
import { argument, constant, option } from "@optique/core/primitives";
import { integer, string, url } from "@optique/core/valueparser";
import { run } from "@optique/run";

const parser = or(
  // Server mode
  object({
    mode: constant("server"),
    port: option("-p", "--port", integer({ min: 1, max: 65535 })),
    host: withDefault(option("-h", "--host", string()), "0.0.0.0"),
  }),
  // Client mode
  object({
    mode: constant("client"),
    url: argument(url()),
  }),
);

const config = run(parser);

The or() combinator tries each alternative in order. The first one that successfully parses wins. The constant() parser adds a literal value to the result without consuming any input, which serves as a discriminator.

TypeScript infers a discriminated union:

type Config =
  | { mode: "server"; port: number; host: string }
  | { mode: "client"; url: URL };

Now you can write type-safe code that handles each mode:

if (config.mode === "server") {
  console.log(`Starting server on ${config.host}:${config.port}`);
} else {
  console.log(`Connecting to ${config.url.hostname}`);
}

Try accessing config.url in the server branch. TypeScript won't let you. The compiler knows that when mode is "server", only port and host exist.

This is the key difference from configuration-based libraries. With Commander or Yargs, you'd get a type like { port?: number; host?: string; url?: string } and have to check at runtime which combination of fields is actually present. With Optique, the types match the actual constraints of your CLI.

Subcommands

For larger tools, you'll want subcommands. Optique handles this with the command() parser:

import { object, or } from "@optique/core/constructs";
import { optional } from "@optique/core/modifiers";
import { argument, command, constant, option } from "@optique/core/primitives";
import { string } from "@optique/core/valueparser";
import { run } from "@optique/run";

const parser = or(
  command("add", object({
    action: constant("add"),
    key: argument(string({ metavar: "KEY" })),
    value: argument(string({ metavar: "VALUE" })),
  })),
  command("remove", object({
    action: constant("remove"),
    key: argument(string({ metavar: "KEY" })),
  })),
  command("list", object({
    action: constant("list"),
    pattern: optional(option("-p", "--pattern", string())),
  })),
);

const result = run(parser, { help: "both" });

switch (result.action) {
  case "add":
    console.log(`Adding ${result.key}=${result.value}`);
    break;
  case "remove":
    console.log(`Removing ${result.key}`);
    break;
  case "list":
    console.log(`Listing${result.pattern ? ` (filter: ${result.pattern})` : ""}`);
    break;
}

Each subcommand gets its own help text. Run myapp add --help and you'll see only the options relevant to add. Run myapp --help and you'll see a summary of all available commands.

The pattern here is the same as mutually exclusive options: or() to combine alternatives, constant() to add a discriminator. This consistency is one of Optique's strengths. Once you understand the basic combinators, you can build arbitrarily complex CLI structures by composing them.

Shell completion

Optique has built-in shell completion for Bash, zsh, fish, PowerShell, and Nushell. Enable it by passing completion: "both" to run():

const config = run(parser, {
  help: "both",
  version: { mode: "both", value: "1.0.0" },
  completion: "both",
});

Users can then generate completion scripts:

$ myapp --completion bash >> ~/.bashrc
$ myapp --completion zsh >> ~/.zshrc
$ myapp --completion fish > ~/.config/fish/completions/myapp.fish

The completions are context-aware. They know about your subcommands, option values, and choice() alternatives. Type myapp --format <TAB> and you'll see json, yaml, toml as suggestions. Type myapp a<TAB> and it'll complete to myapp add.

Completion support is often an afterthought in CLI tools, but it makes a real difference in user experience. With Optique, you get it essentially for free.

Integrating with validation libraries

Already using Zod for validation in your project? The @optique/zod package lets you reuse those schemas as CLI value parsers:

import { z } from "zod";
import { zod } from "@optique/zod";
import { option } from "@optique/core/primitives";

const email = option("--email", zod(z.string().email()));
const port = option("--port", zod(z.coerce.number().int().min(1).max(65535)));

Your existing validation logic just works. The Zod error messages are passed through to the user, so you get the same helpful feedback you're used to.

Prefer Valibot? The @optique/valibot package works the same way:

import * as v from "valibot";
import { valibot } from "@optique/valibot";
import { option } from "@optique/core/primitives";

const email = option("--email", valibot(v.pipe(v.string(), v.email())));

Valibot's bundle size is significantly smaller than Zod's (~10KB vs ~52KB), which can matter for CLI tools where startup time is noticeable.

Tips

A few things I've learned building CLIs with Optique:

Start simple. Begin with object() and basic options. Add or() for mutually exclusive groups only when you need them. It's easy to over-engineer CLI parsers.

Use descriptive metavars. Instead of string(), write string({ metavar: "FILE" }) or string({ metavar: "URL" }). The metavar appears in help text and error messages, so it's worth the extra few characters.

Leverage withDefault(). It's better than making options optional and checking for undefined everywhere. Your code becomes cleaner when you can assume values are always present.

Test your parser. Optique's core parsing functions work without process.argv, so you can unit test your parser logic:

import { parse } from "@optique/core/parser";

const result = parse(parser, ["--name", "Alice", "--count", "3"]);
if (result.success) {
  assert.equal(result.value.name, "Alice");
  assert.equal(result.value.count, 3);
}

This is especially valuable for complex parsers with many edge cases.

Going further

We've covered the fundamentals, but Optique has more to offer:

Async value parsers for validating against external sources, like checking if a Git branch exists or if a URL is reachable
Path validation with path() for checking file existence, directory structure, and file extensions
Custom value parsers for domain-specific types (though Zod/Valibot integration is usually easier)
Reusable option groups with merge() for sharing common options across subcommands
The @optique/temporal package for parsing dates and times using the Temporal API

Check out the documentation for the full picture. The tutorial walks through the concepts in more depth, and the cookbook has patterns for common scenarios.

That's it

Building CLIs in TypeScript doesn't have to mean fighting with types or writing endless runtime validation. Optique lets you express constraints in a way that TypeScript actually understands, so the compiler catches mistakes before they reach production.

The source is on GitHub, and packages are available on both npm and JSR.

Questions or feedback? Find me on the fediverse or open an issue on the GitHub repo.

Designing type-safe sync/async mode support in TypeScript

Hong Minhee — Fri, 02 Jan 2026 05:58:31 +0000

I recently added sync/async mode support to Optique, a type-safe CLI parser for TypeScript. It turned out to be one of the trickier features I've implemented—the object() combinator alone needed to compute a combined mode from all its child parsers, and TypeScript's inference kept hitting edge cases.

What is Optique?

Optique is a type-safe, combinatorial CLI parser for TypeScript, inspired by Haskell's optparse-applicative. Instead of decorators or builder patterns, you compose small parsers into larger ones using combinators, and TypeScript infers the result types.

Here's a quick taste:

import { object } from "@optique/core/constructs";
import { argument, option } from "@optique/core/primitives";
import { string, integer } from "@optique/core/valueparser";
import { run } from "@optique/run";

const cli = object({
  name: argument(string()),
  count: option("-n", "--count", integer()),
});

// TypeScript infers: { name: string; count: number | undefined }
const result = run(cli);  // sync by default

The type inference works through arbitrarily deep compositions—in most cases, you don't need explicit type annotations.

How it started

Lucas Garron (@lgarron) opened an issue requesting async support for shell completions. He wanted to provide Tab-completion suggestions by running shell commands like git for-each-ref to list branches and tags.

// Lucas's example: fetching Git branches and tags in parallel
const [branches, tags] = await Promise.all([
  $`git for-each-ref --format='%(refname:short)' refs/heads/`.text(),
  $`git for-each-ref --format='%(refname:short)' refs/tags/`.text(),
]);

At first, I didn't like the idea. Optique's entire API was synchronous, which made it simpler to reason about and avoided the “async infection” problem where one async function forces everything upstream to become async. I argued that shell completion should be near-instantaneous, and if you need async data, you should cache it at startup.

But Lucas pushed back. The filesystem is a database, and many useful completions inherently require async work—Git refs change constantly, and pre-caching everything at startup doesn't scale for large repos. Fair point.

What I needed to solve

So, how do you support both sync and async execution modes in a composable parser library while maintaining type safety?

The key requirements were:

parse() returns T or Promise<T>
complete() returns T or Promise<T>
suggest() returns Iterable<T> or AsyncIterable<T>
When combining parsers, if any parser is async, the combined result must be async
Existing sync code should continue to work unchanged

The fourth requirement is the tricky one. Consider this:

const syncParser = flag("--verbose");
const asyncParser = option("--branch", asyncValueParser);

// What's the type of this?
const combined = object({ verbose: syncParser, branch: asyncParser });

The combined parser should be async because one of its fields is async. This means we need type-level logic to compute the combined mode.

Five design options

I explored five different approaches, each with its own trade-offs.

Option A: conditional types with mode parameter

Add a mode type parameter to Parser and use conditional types:

type Mode = "sync" | "async";

type ModeValue<M extends Mode, T> = M extends "async" ? Promise<T> : T;

interface Parser<M extends Mode, TValue, TState> {
  parse(context: ParserContext<TState>): ModeValue<M, ParserResult<TState>>;
  // ...
}

The challenge is computing combined modes:

type CombineModes<T extends Record<string, Parser<any, any, any>>> =
  T[keyof T] extends Parser<infer M, any, any>
    ? M extends "async" ? "async" : "sync"
    : never;

Option B: mode parameter with default value

A variant of Option A, but place the mode parameter first with a default of "sync":

interface Parser<M extends Mode = "sync", TValue, TState> {
  readonly $mode: M;
  // ...
}

The default value maintains backward compatibility—existing user code keeps working without changes.

Option C: separate interfaces

Define completely separate Parser and AsyncParser interfaces with explicit conversion:

interface Parser<TValue, TState> { /* sync methods */ }
interface AsyncParser<TValue, TState> { /* async methods */ }

function toAsync<T, S>(parser: Parser<T, S>): AsyncParser<T, S>;

Simpler to understand, but requires code duplication and explicit conversions.

Option D: union return types for suggest() only

The minimal approach. Only allow suggest() to be async:

interface Parser<TValue, TState> {
  parse(context: ParserContext<TState>): ParserResult<TState>;  // always sync
  suggest(context: ParserContext<TState>, prefix: string):
    Iterable<Suggestion> | AsyncIterable<Suggestion>;  // can be either
}

This addresses the original use case but doesn't help if async parse() is ever needed.

Option E: fp-ts style HKT simulation

Use the technique from fp-ts to simulate Higher-Kinded Types:

interface URItoKind<A> {
  Identity: A;
  Promise: Promise<A>;
}

type Kind<F extends keyof URItoKind<any>, A> = URItoKind<A>[F];

interface Parser<F extends keyof URItoKind<any>, TValue, TState> {
  parse(context: ParserContext<TState>): Kind<F, ParserResult<TState>>;
}

The most flexible approach, but with a steep learning curve.

Testing the idea

Rather than commit to an approach based on theoretical analysis, I created a prototype to test how well TypeScript handles the type inference in practice. I published my findings in the GitHub issue:

Both approaches correctly handle the “any async → all async” rule at the type level. (…) Complex conditional types like ModeValue<CombineParserModes<T>, ParserResult<TState>> sometimes require explicit type casting in the implementation. This only affects library internals. The user-facing API remains clean.

The prototype validated that Option B (explicit mode parameter with default) would work. I chose it for these reasons:

Backward compatible: The default "sync" keeps existing code working
Explicit: The mode is visible in both types and runtime (via a $mode property)
Debuggable: Easy to inspect the current mode at runtime
Better IDE support: Type information is more predictable

How `CombineModes` works

The CombineModes type computes whether a combined parser should be sync or async:

type CombineModes<T extends readonly Mode[]> = "async" extends T[number]
  ? "async"
  : "sync";

This type checks if "async" is present anywhere in the tuple of modes. If so, the result is "async"; otherwise, it's "sync".

For combinators like object(), I needed to extract modes from parser objects and combine them:

// Extract the mode from a single parser
type ParserMode<T> = T extends Parser<infer M, unknown, unknown> ? M : never;

// Combine modes from all values in a record of parsers
type CombineObjectModes<T extends Record<string, Parser<Mode, unknown, unknown>>> =
  CombineModes<{ [K in keyof T]: ParserMode<T[K]> }[keyof T][]>;

Runtime implementation

The type system handles compile-time safety, but the implementation also needs runtime logic. Each parser has a $mode property that indicates its execution mode:

const syncParser = option("-n", "--name", string());
console.log(syncParser.$mode);  // "sync"

const asyncParser = option("-b", "--branch", asyncValueParser);
console.log(asyncParser.$mode);  // "async"

Combinators compute their mode at construction time:

function object<T extends Record<string, Parser<Mode, unknown, unknown>>>(
  parsers: T
): Parser<CombineObjectModes<T>, ObjectValue<T>, ObjectState<T>> {
  const parserKeys = Reflect.ownKeys(parsers);
  const combinedMode: Mode = parserKeys.some(
    (k) => parsers[k as keyof T].$mode === "async"
  ) ? "async" : "sync";

  // ... implementation
}

Refining the API

Lucas suggested an important refinement during our discussion. Instead of having run() automatically choose between sync and async based on the parser mode, he proposed separate functions:

Perhaps run(…) could be automatic, and runSync(…) and runAsync(…) could enforce that the inferred type matches what is expected.

So we ended up with:

run(): automatic based on parser mode
runSync(): enforces sync mode at compile time
runAsync(): enforces async mode at compile time

// Automatic: returns T for sync parsers, Promise<T> for async
const result1 = run(syncParser);  // string
const result2 = run(asyncParser);  // Promise<string>

// Explicit: compile-time enforcement
const result3 = runSync(syncParser);  // string
const result4 = runAsync(asyncParser);  // Promise<string>

// Compile error: can't use runSync with async parser
const result5 = runSync(asyncParser);  // Type error!

I applied the same pattern to parse()/parseSync()/parseAsync() and suggest()/suggestSync()/suggestAsync() in the facade functions.

Creating async value parsers

With the new API, creating an async value parser for Git branches looks like this:

import type { Suggestion } from "@optique/core/parser";
import type { ValueParser, ValueParserResult } from "@optique/core/valueparser";

function gitRef(): ValueParser<"async", string> {
  return {
    $mode: "async",
    metavar: "REF",
    parse(input: string): Promise<ValueParserResult<string>> {
      return Promise.resolve({ success: true, value: input });
    },
    format(value: string): string {
      return value;
    },
    async *suggest(prefix: string): AsyncIterable<Suggestion> {
      const { $ } = await import("bun");
      const [branches, tags] = await Promise.all([
        $`git for-each-ref --format='%(refname:short)' refs/heads/`.text(),
        $`git for-each-ref --format='%(refname:short)' refs/tags/`.text(),
      ]);
      for (const ref of [...branches.split("\n"), ...tags.split("\n")]) {
        const trimmed = ref.trim();
        if (trimmed && trimmed.startsWith(prefix)) {
          yield { kind: "literal", text: trimmed };
        }
      }
    },
  };
}

Notice that parse() returns Promise.resolve() even though it's synchronous. This is because the ValueParser<"async", T> type requires all methods to use async signatures. Lucas pointed out this is a minor ergonomic issue. If only suggest() needs to be async, you still have to wrap parse() in a Promise.

I considered per-method mode granularity (e.g., ValueParser<ParseMode, SuggestMode, T>), but the implementation complexity would multiply substantially. For now, the workaround is simple enough:

// Option 1: Use Promise.resolve()
parse(input) {
  return Promise.resolve({ success: true, value: input });
}

// Option 2: Mark as async and suppress the linter
// biome-ignore lint/suspicious/useAwait: sync implementation in async ValueParser
async parse(input) {
  return { success: true, value: input };
}

What it cost

Supporting dual modes added significant complexity to Optique's internals. Every combinator needed updates:

Type signatures grew more complex with mode parameters
Mode propagation logic had to be added to every combinator
Dual implementations were needed for sync and async code paths
Type casts were sometimes necessary in the implementation to satisfy TypeScript

For example, the object() combinator went from around 100 lines to around 250 lines. The internal implementation uses conditional logic based on the combined mode:

if (combinedMode === "async") {
  return {
    $mode: "async" as M,
    // ... async implementation with Promise chains
    async parse(context) {
      // ... await each field's parse result
    },
  };
} else {
  return {
    $mode: "sync" as M,
    // ... sync implementation
    parse(context) {
      // ... directly call each field's parse
    },
  };
}

This duplication is the cost of supporting both modes without runtime overhead for sync-only use cases.

Lessons learned

Listen to users, but validate with prototypes

My initial instinct was to resist async support. Lucas's persistence and concrete examples changed my mind, but I validated the approach with a prototype before committing. The prototype revealed practical issues (like TypeScript inference limits) that pure design analysis would have missed.

Backward compatibility is worth the complexity

Making "sync" the default mode meant existing code continued to work unchanged. This was a deliberate choice. Breaking changes should require user action, not break silently.

Unified mode vs per-method granularity

I chose unified mode (all methods share the same sync/async mode) over per-method granularity. This means users occasionally write
Promise.resolve() for methods that don't actually need async, but the alternative was multiplicative complexity in the type system.

Designing in public

The entire design process happened in a public GitHub issue. Lucas, Giuseppe, and others contributed ideas that shaped the final API. The runSync()/runAsync() distinction came directly from Lucas's feedback.

Conclusion

This was one of the more challenging features I've implemented in Optique. TypeScript's type system is powerful enough to encode the “any async means all async” rule at compile time, but getting there required careful design work and prototyping.

What made it work: conditional types like ModeValue<M, T> can bridge the gap between sync and async worlds. You pay for it with implementation complexity, but the user-facing API stays clean and type-safe.

Optique 0.9.0 with async support is currently in pre-release testing. If you'd like to try it, check out PR #70 or install the pre-release:

npm  add       @optique/core@0.9.0-dev.212 @optique/run@0.9.0-dev.212
deno add --jsr @optique/core@0.9.0-dev.212 @optique/run@0.9.0-dev.212

Feedback is welcome!

Logging in Node.js (or Deno or Bun or edge functions) in 2026

Hong Minhee — Thu, 01 Jan 2026 14:58:25 +0000

It's 2 AM. Something is wrong in production. Users are complaining, but you're not sure what's happening—your only clues are a handful of console.log statements you sprinkled around during development. Half of them say things like “here” or “this works.” The other half dump entire objects that scroll off the screen. Good luck.

We've all been there. And yet, setting up “proper” logging often feels like overkill. Traditional logging libraries like winston or Pino come with their own learning curves, configuration formats, and assumptions about how you'll deploy your app. If you're working with edge functions or trying to keep your bundle small, adding a logging library can feel like bringing a sledgehammer to hang a picture frame.

I'm a fan of the “just enough” approach—more than raw console.log, but without the weight of a full-blown logging framework. We'll start from console.log(), understand its real limitations (not the exaggerated ones), and work toward a setup that's actually useful. I'll be using LogTape for the examples—it's a zero-dependency logging library that works across Node.js, Deno, Bun, and edge functions, and stays out of your way when you don't need it.

Starting with console methods—and where they fall short

The console object is JavaScript's great equalizer. It's built-in, it works everywhere, and it requires zero setup. You even get basic severity levels: console.debug(), console.info(), console.warn(), and console.error(). In browser DevTools and some terminal environments, these show up with different colors or icons.

console.debug("Connecting to database...");
console.info("Server started on port 3000");
console.warn("Cache miss for user 123");
console.error("Failed to process payment");

For small scripts or quick debugging, this is perfectly fine. But once your application grows beyond a few files, the cracks start to show:

No filtering without code changes. Want to hide debug messages in production? You'll need to wrap every console.debug() call in a conditional, or find-and-replace them all. There's no way to say “show me only warnings and above” at runtime.

Everything goes to the console. What if you want to write logs to a file? Send errors to Sentry? Stream logs to CloudWatch? You'd have to replace every console.* call with something else—and hope you didn't miss any.

No context about where logs come from. When your app has dozens of modules, a log message like “Connection failed” doesn't tell you much. Was it the database? The cache? A third-party API? You end up prefixing every message manually: console.error("[database] Connection failed").

No structured data. Modern log analysis tools work best with structured data (JSON). But console.log("User logged in", { userId: 123 }) just prints User logged in { userId: 123 } as a string—not very useful for querying later.

Libraries pollute your logs. If you're using a library that logs with console.*, those messages show up whether you want them or not. And if you're writing a library, your users might not appreciate unsolicited log messages.

What you actually need from a logging system

Before diving into code, let's think about what would actually solve the problems above. Not a wish list of features, but the practical stuff that makes a difference when you're debugging at 2 AM or trying to understand why requests are slow.

Log levels with filtering

A logging system should let you categorize messages by severity—trace, debug, info, warning, error, fatal—and then filter them based on what you need. During development, you want to see everything. In production, maybe just warnings and above. The key is being able to change this without touching your code.

Sinks (multiple output destinations)

“Sink” is just a fancy word for “where logs go.” You might want logs to go to the console during development, to files in production, and to an external service like Sentry or CloudWatch for errors. A good logging system lets you configure multiple sinks and route different logs to different destinations.

Structured logging

Instead of logging strings, you log objects with properties. This makes logs machine-readable and queryable:

// Instead of this:
logger.info("User 123 logged in from 192.168.1.1");

// You do this:
logger.info("User logged in", { userId: 123, ip: "192.168.1.1" });

Now you can search for all logs where userId === 123 or filter by IP address.

Context for request tracing

In a web server, you often want all logs from a single request to share a common identifier (like a request ID). This makes it possible to trace a request's journey through your entire system.

Getting started with LogTape

There are plenty of logging libraries out there. winston has been around forever and has a plugin for everything. Pino is fast and outputs JSON. bunyan, log4js, signale—the list goes on.

So why LogTape? A few reasons stood out to me:

Zero dependencies. Not “few dependencies”—actually zero. In an era where a single npm install can pull in hundreds of packages, this matters for security, bundle size, and not having to wonder why your lockfile just changed.

Works everywhere. The same code runs on Node.js, Deno, Bun, browsers, and edge functions like Cloudflare Workers. No polyfills, no conditional imports, no “this feature only works on Node.”

Doesn't force itself on users. If you're writing a library, you can add logging without your users ever knowing—unless they want to see the logs. This is a surprisingly rare feature.

Let's set it up:

npm add @logtape/logtape       # npm
pnpm add @logtape/logtape      # pnpm
yarn add @logtape/logtape      # Yarn
deno add jsr:@logtape/logtape  # Deno
bun add @logtape/logtape       # Bun

Configuration happens once, at your application's entry point:

import { configure, getConsoleSink, getLogger } from "@logtape/logtape";

await configure({
  sinks: {
    console: getConsoleSink(),  // Where logs go
  },
  loggers: [
    { category: ["my-app"], lowestLevel: "debug", sinks: ["console"] },  // What to log
  ],
});

// Now you can log from anywhere in your app:
const logger = getLogger(["my-app", "server"]);
logger.info`Server started on port 3000`;
logger.debug`Request received: ${{ method: "GET", path: "/api/users" }}`;

Notice a few things:

Configuration is explicit. You decide where logs go (sinks) and which logs to show (lowestLevel).
Categories are hierarchical. The logger ["my-app", "server"] inherits settings from ["my-app"].
Template literals work. You can use backticks for a natural logging syntax.

Categories and filtering: Controlling log verbosity

Here's a scenario: you're debugging a database issue. You want to see every query, every connection attempt, every retry. But you don't want to wade through thousands of HTTP request logs to find them.

Categories let you solve this. Instead of one global log level, you can set different verbosity for different parts of your application.

await configure({
  sinks: {
    console: getConsoleSink(),
  },
  loggers: [
    { category: ["my-app"], lowestLevel: "info", sinks: ["console"] },  // Default: info and above
    { category: ["my-app", "database"], lowestLevel: "debug", sinks: ["console"] },  // DB module: show debug too
  ],
});

Now when you log from different parts of your app:

// In your database module:
const dbLogger = getLogger(["my-app", "database"]);
dbLogger.debug`Executing query: ${sql}`;  // This shows up

// In your HTTP module:
const httpLogger = getLogger(["my-app", "http"]);
httpLogger.debug`Received request`;  // This is filtered out (below "info")
httpLogger.info`GET /api/users 200`;  // This shows up

Controlling third-party library logs

If you're using libraries that also use LogTape, you can control their logs separately:

await configure({
  sinks: { console: getConsoleSink() },
  loggers: [
    { category: ["my-app"], lowestLevel: "debug", sinks: ["console"] },
    // Only show warnings and above from some-library
    { category: ["some-library"], lowestLevel: "warning", sinks: ["console"] },
  ],
});

The root logger

Sometimes you want a catch-all configuration. The root logger (empty category []) catches everything:

await configure({
  sinks: { console: getConsoleSink() },
  loggers: [
    // Catch all logs at info level
    { category: [], lowestLevel: "info", sinks: ["console"] },
    // But show debug for your app
    { category: ["my-app"], lowestLevel: "debug", sinks: ["console"] },
  ],
});

Log levels and when to use them

LogTape has six log levels. Choosing the right one isn't just about severity—it's about who needs to see the message and when.

Level	When to use it
`trace`	Very detailed diagnostic info. Loop iterations, function entry/exit. Usually only enabled when hunting a specific bug.
`debug`	Information useful during development. Variable values, state changes, flow control decisions.
`info`	Normal operational messages. “Server started,” “User logged in,” “Job completed.”
`warning`	Something unexpected happened, but the app can continue. Deprecated API usage, retry attempts, missing optional config.
`error`	Something failed. An operation couldn't complete, but the app is still running.
`fatal`	The app is about to crash or is in an unrecoverable state.

const logger = getLogger(["my-app"]);

logger.trace`Entering processUser function`;
logger.debug`Processing user ${{ userId: 123 }}`;
logger.info`User successfully created`;
logger.warn`Rate limit approaching: ${980}/1000 requests`;
logger.error`Failed to save user: ${error.message}`;
logger.fatal`Database connection lost, shutting down`;

A good rule of thumb: in production, you typically run at info or warning level. During development or when debugging, you drop down to debug or trace.

Structured logging: Beyond plain text

At some point, you'll want to search your logs. “Show me all errors from the payment service in the last hour.” “Find all requests from user 12345.” “What's the average response time for the /api/users endpoint?”

If your logs are plain text strings, these queries are painful. You end up writing regexes, hoping the log format is consistent, and cursing past-you for not thinking ahead.

Structured logging means attaching data to your logs as key-value pairs, not just embedding them in strings. This makes logs machine-readable and queryable.

LogTape supports two syntaxes for this:

Template literals (great for simple messages)

const userId = 123;
const action = "login";
logger.info`User ${userId} performed ${action}`;

Message templates with properties (great for structured data)

logger.info("User performed action", {
  userId: 123,
  action: "login",
  ip: "192.168.1.1",
  timestamp: new Date().toISOString(),
});

You can reference properties in your message using placeholders:

logger.info("User {userId} logged in from {ip}", {
  userId: 123,
  ip: "192.168.1.1",
});
// Output: User 123 logged in from 192.168.1.1

Nested property access

LogTape supports dot notation and array indexing in placeholders:

logger.info("Order {order.id} placed by {order.customer.name}", {
  order: {
    id: "ORD-001",
    customer: { name: "Alice", email: "alice@example.com" },
  },
});

logger.info("First item: {items[0].name}", {
  items: [{ name: "Widget", price: 9.99 }],
});

Machine-readable output with JSON Lines

For production, you often want logs as JSON (one object per line). LogTape has a built-in formatter for this:

import { configure, getConsoleSink, jsonLinesFormatter } from "@logtape/logtape";

await configure({
  sinks: {
    console: getConsoleSink({ formatter: jsonLinesFormatter }),
  },
  loggers: [
    { category: [], lowestLevel: "info", sinks: ["console"] },
  ],
});

Output:

{"@timestamp":"2026-01-15T10:30:00.000Z","level":"INFO","message":"User logged in","logger":"my-app","properties":{"userId":123}}

Sending logs to different destinations (sinks)

So far we've been sending everything to the console. That's fine for development, but in production you'll likely want logs to go elsewhere—or to multiple places at once.

Think about it: console output disappears when the process restarts. If your server crashes at 3 AM, you want those logs to be somewhere persistent. And when an error occurs, you might want it to show up in your error tracking service immediately, not just sit in a log file waiting for someone to grep through it.

This is where sinks come in. A sink is just a function that receives log records and does something with them. LogTape comes with several built-in sinks, and creating your own is trivial.

Console sink

The simplest sink—outputs to the console:

import { getConsoleSink } from "@logtape/logtape";

const consoleSink = getConsoleSink();

File sink

For writing logs to files, install the @logtape/file package:

npm add @logtape/file

import { getFileSink, getRotatingFileSink } from "@logtape/file";

// Simple file sink
const fileSink = getFileSink("app.log");

// Rotating file sink (rotates when file reaches 10MB, keeps 5 old files)
const rotatingFileSink = getRotatingFileSink("app.log", {
  maxSize: 10 * 1024 * 1024,  // 10MB
  maxFiles: 5,
});

Why rotating files? Without rotation, your log file grows indefinitely until it fills up the disk. With rotation, old logs are automatically archived and eventually deleted, keeping disk usage under control. This is especially important for long-running servers.

External services

For production systems, you often want logs to go to specialized services that provide search, alerting, and visualization. LogTape has packages for popular services:

// OpenTelemetry (for observability platforms like Jaeger, Honeycomb, Datadog)
import { getOpenTelemetrySink } from "@logtape/otel";

// Sentry (for error tracking with stack traces and context)
import { getSentrySink } from "@logtape/sentry";

// AWS CloudWatch Logs (for AWS-native log aggregation)
import { getCloudWatchLogsSink } from "@logtape/cloudwatch-logs";

The OpenTelemetry sink is particularly useful if you're already using OpenTelemetry for tracing—your logs will automatically correlate with your traces, making debugging distributed systems much easier.

Multiple sinks

Here's where things get interesting. You can send different logs to different destinations based on their level or category:

await configure({
  sinks: {
    console: getConsoleSink(),
    file: getFileSink("app.log"),
    errors: getSentrySink(),
  },
  loggers: [
    { category: [], lowestLevel: "info", sinks: ["console", "file"] },  // Everything to console + file
    { category: [], lowestLevel: "error", sinks: ["errors"] },  // Errors also go to Sentry
  ],
});

Notice that a log record can go to multiple sinks. An error log in this configuration goes to the console, the file, and Sentry. This lets you have comprehensive local logs while also getting immediate alerts for critical issues.

Custom sinks

Sometimes you need to send logs somewhere that doesn't have a pre-built sink. Maybe you have an internal logging service, or you want to send logs to a Slack channel, or store them in a database.

A sink is just a function that takes a LogRecord. That's it:

import type { Sink } from "@logtape/logtape";

const slackSink: Sink = (record) => {
  // Only send errors and fatals to Slack
  if (record.level === "error" || record.level === "fatal") {
    fetch("https://hooks.slack.com/services/YOUR/WEBHOOK/URL", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        text: `[${record.level.toUpperCase()}] ${record.message.join("")}`,
      }),
    });
  }
};

The simplicity of sink functions means you can integrate LogTape with virtually any logging backend in just a few lines of code.

Request tracing with contexts

Here's a scenario you've probably encountered: a user reports an error, you check the logs, and you find a sea of interleaved messages from dozens of concurrent requests. Which log lines belong to the user's request? Good luck figuring that out.

This is where request tracing comes in. The idea is simple: assign a unique identifier to each request, and include that identifier in every log message produced while handling that request. Now you can filter your logs by request ID and see exactly what happened, in order, for that specific request.

LogTape supports this through contexts—a way to attach properties to log messages without passing them around explicitly.

Explicit context

The simplest approach is to create a logger with attached properties using .with():

function handleRequest(req: Request) {
  const requestId = crypto.randomUUID();
  const logger = getLogger(["my-app", "http"]).with({ requestId });

  logger.info`Request received`;  // Includes requestId automatically
  processRequest(req, logger);
  logger.info`Request completed`;  // Also includes requestId
}

This works well when you're passing the logger around explicitly. But what about code that's deeper in your call stack? What about code in libraries that don't know about your logger instance?

Implicit context

This is where implicit contexts shine. Using withContext(), you can set properties that automatically appear in all log messages within a callback—even in nested function calls, async operations, and third-party libraries (as long as they use LogTape).

First, enable implicit contexts in your configuration:

import { configure, getConsoleSink } from "@logtape/logtape";
import { AsyncLocalStorage } from "node:async_hooks";

await configure({
  sinks: { console: getConsoleSink() },
  loggers: [
    { category: ["my-app"], lowestLevel: "debug", sinks: ["console"] },
  ],
  contextLocalStorage: new AsyncLocalStorage(),
});

Then use withContext() in your request handler:

import { withContext, getLogger } from "@logtape/logtape";

function handleRequest(req: Request) {
  const requestId = crypto.randomUUID();

  return withContext({ requestId }, async () => {
    // Every log message in this callback includes requestId—automatically
    const logger = getLogger(["my-app"]);
    logger.info`Processing request`;

    await validateInput(req);   // Logs here include requestId
    await processBusinessLogic(req);  // Logs here too
    await saveToDatabase(req);  // And here

    logger.info`Request complete`;
  });
}

The magic is that validateInput, processBusinessLogic, and saveToDatabase don't need to know anything about the request ID. They just call getLogger() and log normally, and the request ID appears in their logs automatically. This works even across async boundaries—the context follows the execution flow, not the call stack.

This is incredibly powerful for debugging. When something goes wrong, you can search for the request ID and see every log message from every module that was involved in handling that request.

Framework integrations

Setting up request tracing manually can be tedious. LogTape has dedicated packages for popular frameworks that handle this automatically:

// Express
import { expressLogger } from "@logtape/express";
app.use(expressLogger());

// Fastify
import { getLogTapeFastifyLogger } from "@logtape/fastify";
const app = Fastify({ loggerInstance: getLogTapeFastifyLogger() });

// Hono
import { honoLogger } from "@logtape/hono";
app.use(honoLogger());

// Koa
import { koaLogger } from "@logtape/koa";
app.use(koaLogger());

These middlewares automatically generate request IDs, set up implicit contexts, and log request/response information. You get comprehensive request logging with a single line of code.

Using LogTape in libraries vs applications

If you've ever used a library that spams your console with unwanted log messages, you know how annoying it can be. And if you've ever tried to add logging to your own library, you've faced a dilemma: should you use console.log() and annoy your users? Require them to install and configure a specific logging library? Or just... not log anything?

LogTape solves this with its library-first design. Libraries can add as much logging as they want, and it costs their users nothing unless they explicitly opt in.

If you're writing a library

The rule is simple: use getLogger() to log, but never call configure(). Configuration is the application's responsibility, not the library's.

// my-library/src/database.ts
import { getLogger } from "@logtape/logtape";

const logger = getLogger(["my-library", "database"]);

export function connect(url: string) {
  logger.debug`Connecting to ${url}`;
  // ... connection logic ...
  logger.info`Connected successfully`;
}

What happens when someone uses your library?

If they haven't configured LogTape, nothing happens. The log calls are essentially no-ops—no output, no errors, no performance impact. Your library works exactly as if the logging code wasn't there.

If they have configured LogTape, they get full control. They can see your library's debug logs if they're troubleshooting an issue, or silence them entirely if they're not interested. They decide, not you.

This is fundamentally different from using console.log() in a library. With console.log(), your users have no choice—they see your logs whether they want to or not. With LogTape, you give them the power to decide.

If you're writing an application

You configure LogTape once in your entry point. This single configuration controls logging for your entire application, including any libraries that use LogTape:

await configure({
  sinks: { console: getConsoleSink() },
  loggers: [
    { category: ["my-app"], lowestLevel: "debug", sinks: ["console"] },  // Your app: verbose
    { category: ["my-library"], lowestLevel: "warning", sinks: ["console"] },  // Library: quiet
    { category: ["noisy-library"], lowestLevel: "fatal", sinks: [] },  // That one library: silent
  ],
});

This separation of concerns—libraries log, applications configure—makes for a much healthier ecosystem. Library authors can add detailed logging for debugging without worrying about annoying their users. Application developers can tune logging to their needs without digging through library code.

Migrating from another logger?

If your application already uses winston, Pino, or another logging library, you don't have to migrate everything at once. LogTape provides adapters that route LogTape logs to your existing logging setup:

import { install } from "@logtape/adaptor-winston";
import winston from "winston";

install(winston.createLogger({ /* your existing config */ }));

This is particularly useful when you want to use a library that uses LogTape, but you're not ready to switch your whole application over. The library's logs will flow through your existing winston (or Pino) configuration, and you can migrate gradually if you choose to.

Production considerations

Development and production have different needs. During development, you want verbose logs, pretty formatting, and immediate feedback. In production, you care about performance, reliability, and not leaking sensitive data. Here are some things to keep in mind.

Non-blocking mode

By default, logging is synchronous—when you call logger.info(), the message is written to the sink before the function returns. This is fine for development, but in a high-throughput production environment, the I/O overhead of writing every log message can add up.

Non-blocking mode buffers log messages and writes them in the background:

const consoleSink = getConsoleSink({ nonBlocking: true });
const fileSink = getFileSink("app.log", { nonBlocking: true });

The tradeoff is that logs might be slightly delayed, and if your process crashes, some buffered logs might be lost. But for most production workloads, the performance benefit is worth it.

Sensitive data redaction

Logs have a way of ending up in unexpected places—log aggregation services, debugging sessions, support tickets. If you're logging request data, user information, or API responses, you might accidentally expose sensitive information like passwords, API keys, or personal data.

LogTape's @logtape/redaction package helps you catch these before they become a problem:

import {
  redactByPattern,
  EMAIL_ADDRESS_PATTERN,
  CREDIT_CARD_NUMBER_PATTERN,
  type RedactionPattern,
} from "@logtape/redaction";
import { defaultConsoleFormatter, configure, getConsoleSink } from "@logtape/logtape";

const BEARER_TOKEN_PATTERN: RedactionPattern = {
  pattern: /Bearer [A-Za-z0-9\-._~+\/]+=*/g,
  replacement: "[REDACTED]",
};

const formatter = redactByPattern(defaultConsoleFormatter, [
  EMAIL_ADDRESS_PATTERN,
  CREDIT_CARD_NUMBER_PATTERN,
  BEARER_TOKEN_PATTERN,
]);

await configure({
  sinks: {
    console: getConsoleSink({ formatter }),
  },
  // ...
});

With this configuration, email addresses, credit card numbers, and bearer tokens are automatically replaced with [REDACTED] in your log output. The @logtape/redaction package comes with built-in patterns for common sensitive data types, and you can define custom patterns for anything else. It's not foolproof—you should still be mindful of what you log—but it provides a safety net.

See the redaction documentation for more patterns and field-based redaction.

Edge functions and serverless

Edge functions (Cloudflare Workers, Vercel Edge Functions, etc.) have a unique constraint: they can be terminated immediately after returning a response. If you have buffered logs that haven't been flushed yet, they'll be lost.

The solution is to explicitly flush logs before returning:

import { configure, dispose } from "@logtape/logtape";

export default {
  async fetch(request, env, ctx) {
    await configure({ /* ... */ });

    // ... handle request ...

    ctx.waitUntil(dispose());  // Flush logs before worker terminates

    return new Response("OK");
  },
};

The dispose() function flushes all buffered logs and cleans up resources. By passing it to ctx.waitUntil(), you ensure the worker stays alive long enough to finish writing logs, even after the response has been sent.

Wrapping up

Logging isn't glamorous, but it's one of those things that makes a huge difference when something goes wrong. The setup I've described here—categories for organization, structured data for queryability, contexts for request tracing—isn't complicated, but it's a significant step up from scattered console.log statements.

LogTape isn't the only way to achieve this, but I've found it hits a nice sweet spot: powerful enough for production use, simple enough that you're not fighting the framework, and light enough that you don't feel guilty adding it to a library.

If you want to dig deeper, the LogTape documentation covers advanced topics like custom filters, the “fingers crossed” pattern for buffering debug logs until an error occurs, and more sink options. The GitHub repository is also a good place to report issues or see what's coming next.

Now go add some proper logging to that side project you've been meaning to clean up. Your future 2 AM self will thank you.

Sending emails in Node.js, Deno, and Bun in 2026: a practical guide

Hong Minhee — Thu, 01 Jan 2026 07:53:42 +0000

So you need to send emails from your JavaScript application. Email remains one of the most essential features in web apps—welcome emails, password resets, notifications—but the ecosystem is fragmented. Nodemailer doesn't work on edge functions. Each provider has its own SDK. And if you're using Deno or Bun, good luck finding libraries that actually work.

This guide covers how to send emails across modern JavaScript runtimes using Upyo, a cross-runtime email library.

Disclosure: I'm the author of Upyo. This guide focuses on Upyo because I built it to solve problems I kept running into, but you should know that going in. If you're looking for alternatives: Nodemailer is the established choice for Node.js (though it doesn't work on Deno/Bun/edge), and most email providers offer their own official SDKs.

TL;DR for the impatient

If you just want working code, here's the quickest path to sending an email:

import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";

const transport = new SmtpTransport({
  host: "smtp.gmail.com",
  port: 465,
  secure: true,
  auth: {
    user: "your-email@gmail.com",
    pass: "your-app-password", // Not your regular password!
  },
});

const message = createMessage({
  from: "your-email@gmail.com",
  to: "recipient@example.com",
  subject: "Hello from my app!",
  content: { text: "This is my first email." },
});

const receipt = await transport.send(message);
if (receipt.successful) {
  console.log("Sent:", receipt.messageId);
} else {
  console.log("Failed:", receipt.errorMessages);
}

Install with:

npm add @upyo/core @upyo/smtp

That's it. This exact code works on Node.js, Deno, and Bun. But if you want to understand what's happening and explore more powerful options, read on.

Why Upyo?

Cross-runtime: Works on Node.js, Deno, Bun, and edge functions with the same API
Zero dependencies: Keeps your bundle small
Provider independence: Switch between SMTP, Mailgun, Resend, SendGrid, or Amazon SES without changing your application code
Type-safe: Full TypeScript support with discriminated unions for error handling
Built for testing: Includes a mock transport for unit tests

Part 1: Getting started with Gmail SMTP

Let's start with the most accessible option: Gmail's SMTP server. It's free, requires no additional accounts, and works great for development and low-volume production use.

Step 1: Generate a Gmail app password

Gmail doesn't allow you to use your regular password for SMTP. You need to create an app-specific password:

Go to your Google Account
Navigate to Security → 2-Step Verification (enable it if you haven't)
At the bottom, click App passwords
Select Mail and your device, then click Generate
Copy the 16-character password

Step 2: Install dependencies

Choose your runtime and package manager:

Node.js

npm add @upyo/core @upyo/smtp
# or: pnpm add @upyo/core @upyo/smtp
# or: yarn add @upyo/core @upyo/smtp

Deno

deno add jsr:@upyo/core jsr:@upyo/smtp

Bun

bun add @upyo/core @upyo/smtp

The same code works across all three runtimes—that's the beauty of Upyo.

Step 3: Send your first email

import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";

// Create the transport (reuse this for multiple emails)
const transport = new SmtpTransport({
  host: "smtp.gmail.com",
  port: 465,
  secure: true,
  auth: {
    user: "your-email@gmail.com",
    pass: "abcd efgh ijkl mnop", // Your app password
  },
});

// Create and send a message
const message = createMessage({
  from: "your-email@gmail.com",
  to: "recipient@example.com",
  subject: "Welcome to my app!",
  content: {
    text: "Thanks for signing up. We're excited to have you!",
    html: "<h1>Welcome!</h1><p>Thanks for signing up. We're excited to have you!</p>",
  },
});

const receipt = await transport.send(message);

if (receipt.successful) {
  console.log("Email sent successfully! Message ID:", receipt.messageId);
} else {
  console.error("Failed to send email:", receipt.errorMessages.join(", "));
}

// Don't forget to close connections when done
await transport.closeAllConnections();

Let me highlight a few important details:

secure: true with port 465: This establishes a TLS-encrypted connection from the start. Gmail requires encryption, so this combination is essential.
Separate text and html content: Always provide both. Some email clients don't render HTML, and spam filters look more favorably on emails with plain text alternatives.
The receipt pattern: Upyo uses discriminated unions for type-safe error handling. When receipt.successful is true, you get messageId. When it's false, you get errorMessages. This makes it impossible to forget error handling.
Closing connections: SMTP maintains persistent TCP connections. Always close them when you're done, or use await using (shown next) to handle this automatically.

Pro tip: automatic resource cleanup with `await using`

Managing resources manually is error-prone—what if an exception occurs before closeAllConnections() is called? Modern JavaScript (ES2024) solves this with explicit resource management.

import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";

// Transport is automatically disposed when it goes out of scope
await using transport = new SmtpTransport({
  host: "smtp.gmail.com",
  port: 465,
  secure: true,
  auth: {
    user: "your-email@gmail.com",
    pass: "your-app-password",
  },
});

const message = createMessage({
  from: "your-email@gmail.com",
  to: "recipient@example.com",
  subject: "Hello!",
  content: { text: "This email was sent with automatic cleanup!" },
});

await transport.send(message);
// No need to call `closeAllConnections()` - it happens automatically!

The await using keyword tells JavaScript to call the transport's cleanup method when execution leaves this scope—even if an error is thrown. This pattern is similar to Python's with statement or C#'s using block. It's supported in Node.js 22+, Deno, and Bun.

What if your environment doesn't support await using?

For older Node.js versions or environments without ES2024 support, use try/finally to ensure cleanup:

const transport = new SmtpTransport({
  host: "smtp.gmail.com",
  port: 465,
  secure: true,
  auth: { user: "your-email@gmail.com", pass: "your-app-password" },
});

try {
  await transport.send(message);
} finally {
  await transport.closeAllConnections();
}

This achieves the same result—cleanup happens whether the send succeeds or throws an error.

Part 2: Adding attachments and rich content

Real-world emails often need more than plain text.

HTML emails with inline images

Inline images appear directly in the email body rather than as downloadable attachments. The trick is to reference them using a Content-ID (CID) URL scheme.

import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";
import { readFile } from "node:fs/promises";

await using transport = new SmtpTransport({
  host: "smtp.gmail.com",
  port: 465,
  secure: true,
  auth: { user: "your-email@gmail.com", pass: "your-app-password" },
});

// Read your logo file
const logoContent = await readFile("./assets/logo.png");

const message = createMessage({
  from: "your-email@gmail.com",
  to: "customer@example.com",
  subject: "Your order confirmation",
  content: {
    html: `
      <div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
        <img src="cid:company-logo" alt="Company Logo" style="width: 150px;">
        <h1>Order Confirmed!</h1>
        <p>Thank you for your purchase. Your order #12345 has been confirmed.</p>
      </div>
    `,
    text: "Order Confirmed! Thank you for your purchase. Your order #12345 has been confirmed.",
  },
  attachments: [
    {
      filename: "logo.png",
      content: logoContent,
      contentType: "image/png",
      contentId: "company-logo", // Referenced as cid:company-logo in HTML
      inline: true,
    },
  ],
});

await transport.send(message);

Key points about inline images:

contentId: This is the identifier you use in the HTML's src="cid:..." attribute. It can be any unique string.
inline: true: This tells the email client to display the image within the message body, not as a separate attachment.
Always include alt text: Some email clients block images by default, so the alt text ensures your message is still understandable.

File attachments

For regular attachments that recipients can download, use the standard File API. This approach works across all JavaScript runtimes.

import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";
import { readFile } from "node:fs/promises";

await using transport = new SmtpTransport({
  host: "smtp.gmail.com",
  port: 465,
  secure: true,
  auth: { user: "your-email@gmail.com", pass: "your-app-password" },
});

// Read files to attach
const invoicePdf = await readFile("./invoices/invoice-2024-001.pdf");
const reportXlsx = await readFile("./reports/monthly-report.xlsx");

const message = createMessage({
  from: "billing@yourcompany.com",
  to: "client@example.com",
  cc: "accounting@yourcompany.com",
  subject: "Invoice #2024-001",
  content: {
    text: "Please find your invoice and monthly report attached.",
  },
  attachments: [
    new File([invoicePdf], "invoice-2024-001.pdf", { type: "application/pdf" }),
    new File([reportXlsx], "monthly-report.xlsx", {
      type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    }),
  ],
  priority: "high", // Sets email priority headers
});

await transport.send(message);

A few notes on attachments:

MIME types matter: Setting the correct type helps email clients display the right icon and open the file with the appropriate application.
priority: "high": This sets the X-Priority header, which some email clients use to highlight important messages. Use it sparingly—overuse can trigger spam filters.

Multiple recipients with different roles

Email supports several recipient types, each with different visibility rules:

import { createMessage } from "@upyo/core";

const message = createMessage({
  from: { name: "Support Team", address: "support@yourcompany.com" },
  to: [
    "primary-recipient@example.com",
    { name: "John Smith", address: "john@example.com" },
  ],
  cc: "manager@yourcompany.com",
  bcc: ["archive@yourcompany.com", "compliance@yourcompany.com"],
  replyTo: "no-reply@yourcompany.com",
  subject: "Your support ticket has been updated",
  content: { text: "We've responded to your ticket #5678." },
});

Understanding recipient types:

to: Primary recipients. Everyone can see who else is in this field.
cc (Carbon Copy): Secondary recipients. Visible to all recipients—use for people who should be informed but aren't the primary audience.
bcc (Blind Carbon Copy): Hidden recipients. No one can see BCC addresses—useful for archiving or compliance without revealing internal processes.
replyTo: Where replies should go. Useful when sending from a no-reply address but wanting responses to reach a real inbox.

You can specify addresses as simple strings ("email@example.com") or as objects with name and address properties for display names.

Part 3: Moving to production with email service providers

Gmail SMTP is great for getting started, but for production applications, you'll want a dedicated email service provider. Here's why:

Higher sending limits: Gmail caps you at ~500 emails/day for personal accounts
Better deliverability: Dedicated services maintain sender reputation and handle bounces properly
Analytics and tracking: See who opened your emails, clicked links, etc.
Webhook notifications: Get real-time callbacks for delivery events
No dependency on personal accounts: Production systems shouldn't rely on someone's Gmail

The best part? With Upyo, switching providers requires minimal code changes—just swap the transport.

Option A: Resend (modern and developer-friendly)

Resend is a newer email service with an excellent developer experience.

npm add @upyo/resend

import { createMessage } from "@upyo/core";
import { ResendTransport } from "@upyo/resend";

const transport = new ResendTransport({
  apiKey: process.env.RESEND_API_KEY!,
});

const message = createMessage({
  from: "hello@yourdomain.com", // Must be verified in Resend
  to: "user@example.com",
  subject: "Welcome aboard!",
  content: {
    text: "Thanks for joining us!",
    html: "<h1>Welcome!</h1><p>Thanks for joining us!</p>",
  },
  tags: ["onboarding", "welcome"], // For analytics
});

const receipt = await transport.send(message);

if (receipt.successful) {
  console.log("Sent via Resend:", receipt.messageId);
}

Notice how similar this looks to the SMTP example? The only differences are the import and the transport configuration. Your message creation and sending logic stays exactly the same—that's Upyo's transport abstraction at work.

Option B: SendGrid (enterprise-grade)

SendGrid is a popular choice for high-volume senders, offering advanced analytics, template management, and a generous free tier.

SendGrid is a popular choice for high-volume senders.

npm add @upyo/sendgrid

import { createMessage } from "@upyo/core";
import { SendGridTransport } from "@upyo/sendgrid";

const transport = new SendGridTransport({
  apiKey: process.env.SENDGRID_API_KEY!,
  clickTracking: true,
  openTracking: true,
});

const message = createMessage({
  from: "notifications@yourdomain.com",
  to: "user@example.com",
  subject: "Your weekly digest",
  content: {
    html: "<h1>This Week's Highlights</h1><p>Here's what you missed...</p>",
    text: "This Week's Highlights\n\nHere's what you missed...",
  },
  tags: ["digest", "weekly"],
});

await transport.send(message);

Option C: Mailgun (reliable workhorse)

Mailgun offers robust infrastructure with strong EU support—important if you need GDPR-compliant data residency.

npm add @upyo/mailgun

import { createMessage } from "@upyo/core";
import { MailgunTransport } from "@upyo/mailgun";

const transport = new MailgunTransport({
  apiKey: process.env.MAILGUN_API_KEY!,
  domain: "mg.yourdomain.com",
  region: "eu", // or "us"
});

const message = createMessage({
  from: "team@yourdomain.com",
  to: "user@example.com",
  subject: "Important update",
  content: { text: "We have some news to share..." },
});

await transport.send(message);

Option D: Amazon SES (cost-effective at scale)

Amazon SES is incredibly affordable—about $0.10 per 1,000 emails. If you're already in the AWS ecosystem, it integrates seamlessly with IAM, CloudWatch, and other services.

npm add @upyo/ses

import { createMessage } from "@upyo/core";
import { SesTransport } from "@upyo/ses";

const transport = new SesTransport({
  authentication: {
    type: "credentials",
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  region: "us-east-1",
  configurationSetName: "my-config-set", // Optional: for tracking
});

const message = createMessage({
  from: "alerts@yourdomain.com",
  to: "admin@example.com",
  subject: "System alert",
  content: { text: "CPU usage exceeded 90%" },
  priority: "high",
});

await transport.send(message);

Part 4: Sending emails from edge functions

Here's where many email solutions fall short. Edge functions (Cloudflare Workers, Vercel Edge, Deno Deploy) run in a restricted environment—they can't open raw TCP connections, which means SMTP is not an option.

You must use an HTTP-based transport like Resend, SendGrid, Mailgun, or Amazon SES. The good news? Your code barely changes.

Cloudflare Workers example

// src/index.ts
import { createMessage } from "@upyo/core";
import { ResendTransport } from "@upyo/resend";

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const transport = new ResendTransport({
      apiKey: env.RESEND_API_KEY,
    });

    const message = createMessage({
      from: "noreply@yourdomain.com",
      to: "user@example.com",
      subject: "Request received",
      content: { text: "We got your request and are processing it." },
    });

    const receipt = await transport.send(message);

    if (receipt.successful) {
      return new Response(`Email sent: ${receipt.messageId}`);
    } else {
      return new Response(`Failed: ${receipt.errorMessages.join(", ")}`, {
        status: 500,
      });
    }
  },
};

interface Env {
  RESEND_API_KEY: string;
}

Vercel Edge Functions example

// app/api/send-email/route.ts
import { createMessage } from "@upyo/core";
import { SendGridTransport } from "@upyo/sendgrid";

export const runtime = "edge";

export async function POST(request: Request) {
  const { to, subject, body } = await request.json();

  const transport = new SendGridTransport({
    apiKey: process.env.SENDGRID_API_KEY!,
  });

  const message = createMessage({
    from: "app@yourdomain.com",
    to,
    subject,
    content: { text: body },
  });

  const receipt = await transport.send(message);

  if (receipt.successful) {
    return Response.json({ success: true, messageId: receipt.messageId });
  } else {
    return Response.json(
      { success: false, errors: receipt.errorMessages },
      { status: 500 }
    );
  }
}

Deno Deploy example

// main.ts
import { createMessage } from "jsr:@upyo/core";
import { MailgunTransport } from "jsr:@upyo/mailgun";

Deno.serve(async (request: Request) => {
  if (request.method !== "POST") {
    return new Response("Method not allowed", { status: 405 });
  }

  const { to, subject, body } = await request.json();

  const transport = new MailgunTransport({
    apiKey: Deno.env.get("MAILGUN_API_KEY")!,
    domain: Deno.env.get("MAILGUN_DOMAIN")!,
    region: "us",
  });

  const message = createMessage({
    from: "noreply@yourdomain.com",
    to,
    subject,
    content: { text: body },
  });

  const receipt = await transport.send(message);

  if (receipt.successful) {
    return Response.json({ success: true, messageId: receipt.messageId });
  } else {
    return Response.json(
      { success: false, errors: receipt.errorMessages },
      { status: 500 }
    );
  }
});

Part 5: Improving deliverability with DKIM

Ever wonder why some emails land in spam while others don't? Email authentication plays a huge role. DKIM (DomainKeys Identified Mail) is one of the key mechanisms—it lets you digitally sign your emails so recipients can verify they actually came from your domain and weren't tampered with in transit.

Without DKIM:

Your emails are more likely to be flagged as spam
Recipients have no way to verify you're really who you claim to be
Sophisticated phishing attacks can impersonate your domain

Setting up DKIM with Upyo

First, generate a DKIM key pair. You can use OpenSSL:

# Generate a 2048-bit RSA private key
openssl genrsa -out dkim-private.pem 2048

# Extract the public key
openssl rsa -in dkim-private.pem -pubout -out dkim-public.pem

Then configure your SMTP transport:

import { createMessage } from "@upyo/core";
import { SmtpTransport } from "@upyo/smtp";
import { readFileSync } from "node:fs";

const transport = new SmtpTransport({
  host: "smtp.example.com",
  port: 587,
  secure: false,
  auth: {
    user: "user@yourdomain.com",
    pass: "password",
  },
  dkim: {
    signatures: [
      {
        signingDomain: "yourdomain.com",
        selector: "mail", // Creates DNS record at mail._domainkey.yourdomain.com
        privateKey: readFileSync("./dkim-private.pem", "utf8"),
        algorithm: "rsa-sha256", // or "ed25519-sha256" for shorter keys
      },
    ],
  },
});

The key configuration options:

signingDomain: Must match your email's "From" domain
selector: An arbitrary name that becomes part of your DNS record (e.g., mail creates a record at mail._domainkey.yourdomain.com)
algorithm: RSA-SHA256 is widely supported; Ed25519-SHA256 offers shorter keys (see below)

Adding the DNS record

Add a TXT record to your domain's DNS:

Name: mail._domainkey (or mail._domainkey.yourdomain.com depending on your DNS provider)
Value: v=DKIM1; k=rsa; p=YOUR_PUBLIC_KEY_HERE

Extract the public key value (remove headers, footers, and newlines from the .pem file):

cat dkim-public.pem | grep -v "^-" | tr -d '\n'

Using Ed25519 for shorter keys

RSA-2048 keys are long—about 400 characters for the public key. This can be problematic because DNS TXT records have size limits, and some DNS providers struggle with long records.

Ed25519 provides equivalent security with much shorter keys (around 44 characters). If your email infrastructure supports it, Ed25519 is the modern choice.

# Generate Ed25519 key pair
openssl genpkey -algorithm ed25519 -out dkim-ed25519-private.pem
openssl pkey -in dkim-ed25519-private.pem -pubout -out dkim-ed25519-public.pem

const transport = new SmtpTransport({
  // ... other config
  dkim: {
    signatures: [
      {
        signingDomain: "yourdomain.com",
        selector: "mail2025",
        privateKey: readFileSync("./dkim-ed25519-private.pem", "utf8"),
        algorithm: "ed25519-sha256",
      },
    ],
  },
});

Part 6: Bulk email sending

When you need to send emails to many recipients—newsletters, notifications, marketing campaigns—you have two approaches:

The wrong way: looping with `send()`

// ❌ Don't do this for bulk sending
for (const subscriber of subscribers) {
  await transport.send(createMessage({
    from: "newsletter@example.com",
    to: subscriber.email,
    subject: "Weekly update",
    content: { text: "..." },
  }));
}

This works, but it's inefficient:

Each send() call waits for the previous one to complete
No automatic batching or optimization
Harder to track overall progress

The right way: using `sendMany()`

The sendMany() method is designed for bulk operations:

import { createMessage } from "@upyo/core";
import { ResendTransport } from "@upyo/resend";

const transport = new ResendTransport({
  apiKey: process.env.RESEND_API_KEY!,
});

const subscribers = [
  { email: "alice@example.com", name: "Alice" },
  { email: "bob@example.com", name: "Bob" },
  { email: "charlie@example.com", name: "Charlie" },
  // ... potentially thousands more
];

// Create personalized messages
const messages = subscribers.map((subscriber) =>
  createMessage({
    from: "newsletter@yourdomain.com",
    to: subscriber.email,
    subject: "Your weekly digest",
    content: {
      html: `<h1>Hi ${subscriber.name}!</h1><p>Here's what's new this week...</p>`,
      text: `Hi ${subscriber.name}!\n\nHere's what's new this week...`,
    },
    tags: ["newsletter", "weekly"],
  })
);

// Send all messages efficiently
let successCount = 0;
let failureCount = 0;

for await (const receipt of transport.sendMany(messages)) {
  if (receipt.successful) {
    successCount++;
  } else {
    failureCount++;
    console.error("Failed:", receipt.errorMessages.join(", "));
  }
}

console.log(`Sent: ${successCount}, Failed: ${failureCount}`);

Why sendMany() is better:

Automatic batching: Some transports (like Resend) combine multiple messages into a single API call
Connection reuse: SMTP transport reuses connections from the pool
Streaming results: You get receipts as they complete, not all at once
Resilient: One failure doesn't stop the rest

Progress tracking for large batches

const totalMessages = messages.length;
let processed = 0;

for await (const receipt of transport.sendMany(messages)) {
  processed++;

  if (processed % 100 === 0) {
    console.log(`Progress: ${processed}/${totalMessages} (${Math.round((processed / totalMessages) * 100)}%)`);
  }

  if (!receipt.successful) {
    console.error(`Message ${processed} failed:`, receipt.errorMessages);
  }
}

console.log("Batch complete!");

When to use `send()` vs `sendMany()`

Scenario	Use
Single transactional email (welcome, password reset)	`send()`
A few emails (under 10)	`send()` in a loop is fine
Newsletters, bulk notifications	`sendMany()`
Batch processing from a queue	`sendMany()`

Part 7: Testing without sending real emails

Upyo includes a MockTransport for testing:

No external dependencies: Tests run offline, in CI, anywhere
Deterministic: No flaky tests due to network issues
Fast: No HTTP requests or SMTP handshakes
Inspectable: You can verify exactly what would have been sent

Basic testing setup

import { createMessage } from "@upyo/core";
import { MockTransport } from "@upyo/mock";
import assert from "node:assert";
import { describe, it, beforeEach } from "node:test";

describe("Email functionality", () => {
  let transport: MockTransport;

  beforeEach(() => {
    transport = new MockTransport();
  });

  it("should send welcome email after registration", async () => {
    // Your application code would call this
    const message = createMessage({
      from: "welcome@yourapp.com",
      to: "newuser@example.com",
      subject: "Welcome to our app!",
      content: { text: "Thanks for signing up!" },
    });

    const receipt = await transport.send(message);

    // Assertions
    assert.strictEqual(receipt.successful, true);
    assert.strictEqual(transport.getSentMessagesCount(), 1);

    const sentMessage = transport.getLastSentMessage();
    assert.strictEqual(sentMessage?.subject, "Welcome to our app!");
    assert.strictEqual(sentMessage?.recipients[0].address, "newuser@example.com");
  });

  it("should handle email failures gracefully", async () => {
    // Simulate a failure
    transport.setNextResponse({
      successful: false,
      errorMessages: ["Invalid recipient address"],
    });

    const message = createMessage({
      from: "test@yourapp.com",
      to: "invalid-email",
      subject: "Test",
      content: { text: "Test" },
    });

    const receipt = await transport.send(message);

    assert.strictEqual(receipt.successful, false);
    assert.ok(receipt.errorMessages.includes("Invalid recipient address"));
  });
});

The key testing methods:

getSentMessagesCount(): How many emails were “sent”
getLastSentMessage(): The most recent message
getSentMessages(): All messages as an array
setNextResponse(): Force the next send to succeed or fail with specific errors

Simulating real-world conditions

import { MockTransport } from "@upyo/mock";

// Simulate network delays
const slowTransport = new MockTransport({
  delay: 500, // 500ms delay per email
});

// Simulate random failures (10% failure rate)
const unreliableTransport = new MockTransport({
  failureRate: 0.1,
});

// Simulate variable latency
const realisticTransport = new MockTransport({
  randomDelayRange: { min: 100, max: 500 },
});

Testing async email workflows

import { MockTransport } from "@upyo/mock";

const transport = new MockTransport();

// Start your async operation that sends emails
startUserRegistration("newuser@example.com");

// Wait for the expected emails to be sent
await transport.waitForMessageCount(2, 5000); // Wait for 2 emails, 5s timeout

// Or wait for a specific email
const welcomeEmail = await transport.waitForMessage(
  (msg) => msg.subject.includes("Welcome"),
  3000
);

console.log("Welcome email was sent:", welcomeEmail.subject);

Part 8: Provider failover with `PoolTransport`

What happens if your email provider goes down? For mission-critical applications, you need redundancy. PoolTransport combines multiple providers with automatic failover—if one fails, it tries the next.

import { PoolTransport } from "@upyo/pool";
import { ResendTransport } from "@upyo/resend";
import { SendGridTransport } from "@upyo/sendgrid";
import { MailgunTransport } from "@upyo/mailgun";
import { createMessage } from "@upyo/core";

// Create multiple transports
const resend = new ResendTransport({ apiKey: process.env.RESEND_API_KEY! });
const sendgrid = new SendGridTransport({ apiKey: process.env.SENDGRID_API_KEY! });
const mailgun = new MailgunTransport({
  apiKey: process.env.MAILGUN_API_KEY!,
  domain: "mg.yourdomain.com",
});

// Combine them with priority-based failover
const transport = new PoolTransport({
  strategy: "priority",
  transports: [
    { transport: resend, priority: 100 },    // Try first
    { transport: sendgrid, priority: 50 },   // Fallback
    { transport: mailgun, priority: 10 },    // Last resort
  ],
  maxRetries: 3,
});

const message = createMessage({
  from: "critical@yourdomain.com",
  to: "admin@example.com",
  subject: "Critical alert",
  content: { text: "This email will try multiple providers if needed." },
});

const receipt = await transport.send(message);
// Automatically tries Resend first, then SendGrid, then Mailgun if others fail

The priority values determine the order—higher numbers are tried first. If Resend fails (network error, rate limit, etc.), the pool automatically retries with SendGrid, then Mailgun.

For more advanced routing strategies (weighted distribution, content-based routing), see the pool transport documentation.

Part 9: Observability with OpenTelemetry

In production, you'll want to track email metrics: send rates, failure rates, latency. Upyo integrates with OpenTelemetry:

import { createOpenTelemetryTransport } from "@upyo/opentelemetry";
import { SmtpTransport } from "@upyo/smtp";

const baseTransport = new SmtpTransport({
  host: "smtp.example.com",
  port: 587,
  auth: { user: "user", pass: "password" },
});

const transport = createOpenTelemetryTransport(baseTransport, {
  serviceName: "email-service",
  tracing: { enabled: true },
  metrics: { enabled: true },
});

// Now all email operations generate traces and metrics automatically
await transport.send(message);

This gives you:

Delivery success/failure rates
Send operation latency histograms
Error classification by type
Distributed tracing for debugging

See the OpenTelemetry documentation for details.

Quick reference: choosing the right transport

Scenario	Recommended Transport
Development/testing	Gmail SMTP or MockTransport
Small production app	Resend or SendGrid
High volume (100k+/month)	Amazon SES
Edge functions	Resend, SendGrid, or Mailgun
Self-hosted infrastructure	SMTP with DKIM
Mission-critical	PoolTransport with failover
EU data residency	Mailgun (EU region) or self-hosted

Wrapping up

This guide covered the most popular transports, but Upyo also supports:

JMAP: Modern email protocol (RFC 8620/8621) for JMAP-compatible servers like Fastmail and Stalwart
Plunk: Developer-friendly email service with self-hosting option

And you can always create a custom transport for any email service not yet supported.

Resources

Have questions or feedback? Feel free to open an issue.

What's been your biggest pain point when sending emails from JavaScript? Let me know in the comments—I'm curious what challenges others have run into.

Upyo (pronounced /oo-pyo/) comes from the Korean word 郵票, meaning “postage stamp.”

Optique: Type-Safe CLI Parser Combinators

Hong Minhee — Wed, 27 Aug 2025 04:09:59 +0000

Recently, I developed a somewhat experimental CLI parser library called Optique. While it has now been released up to version 0.2.0, I think it's an interesting idea worth sharing in this article.

Optique was influenced by two very different libraries. One is Haskell's optparse-applicative library, which taught me that CLI parsers can be parser combinators, and that this approach is incredibly useful. The other is Zod, which TypeScript users are already familiar with. While I got the core idea from optparse-applicative, Haskell and TypeScript are such different languages that there are significant differences in how APIs are structured. So for API design, I referenced various validation libraries including Zod.

Optique expresses what a CLI should look like by assembling small parsers and parser combinators like LEGO blocks. For example, one of the smallest building blocks is option():

const parser = option("-a", "--allow", url());

To execute this parser, you use the run() API:
(Note that the run() function implicitly reads process.argv.slice(2))

const allow: URL = run(parser);

While I've explicitly annotated the URL type in the code above, it's automatically inferred as URL even without the annotation. This parser only accepts the -a/--allow=URL option. It will error if given other options or arguments. It will also error if the -a/--allow=URL option is not provided.

What if we want to make the -a/--allow=URL option optional instead of required? In that case, we wrap the option() parser with the optional() combinator.

const parser = optional(option("-a", "--allow", url()));

What type does this parser produce when executed?

const allow: URL | undefined = run(parser);

Yes, it becomes a URL | undefined type.

Alternatively, let's make it possible to accept multiple -a/--allow=URL options. We want to be able to write:

prog -a https://example.com/ -a https://hackers.pub/

To allow an option to be used multiple times like this, we use the multiple() combinator instead of the optional() combinator:

const parser = multiple(option("-a", "--allow", url()));

Can you start to predict what the result type will be?

const allowList: readonly URL[] = run(parser);

Yes, it becomes a readonly URL[] type.

Now, what if we want to add a mutually exclusive -d/--disallow=URL option that cannot be used together with -a/--allow=URL? Only one of these options should be usable at the same time. In this case, we use the or() combinator:

const parser = or(
  multiple(option("-a", "--allow", url())),
  multiple(option("-d", "--disallow", url())),
);

This parser correctly accepts commands like these:

prog -a https://example.com/ --allow    https://hackers.pub/
prog -d https://example.com/ --disallow https://hackers.pub/

But it will error when -a/--allow=URL and -d/--disallow=URL options are mixed:

prog -a https://example.com/ --disallow https://hackers.pub/

So what type does this parser's result have?

const result: readonly URL[] = run(parser);

Oh, since both parsers wrapped by the or() combinator produce readonly URL[] values, we get readonly URL[] | readonly URL[], which ultimately becomes just readonly URL[]. We'd like to change this to a proper discriminated union format. Something like this type would be ideal:

const Result =
  | { mode: "allowList"; allowList: readonly URL[] }
  | { mode: "blockList"; blockList: readonly URL[] };

When we want to create an object-shaped structure like this, we use the object() combinator:

const parser = or(
  object({
    mode: constant("allowList"),
    allowList: multiple(option("-a", "--allow", url())),
  }),
  object({
    mode: constant("blockList"),
    blockList: multiple(option("-d", "--disallow", url())),
  }),
);

We also used the constant() parser to add a discriminator. This parser is a bit special—it doesn't read anything and just produces the given value. In other words, it's a parser that always succeeds. While it's mainly used for constructing discriminated unions, it can be used in other creative ways.

Now this parser produces the result value with the type we want:

const result:
  | { readonly mode: "allowList"; readonly allowList: readonly URL[] }
  | { readonly mode: "blockList"; readonly blockList: readonly URL[] }
  = run(parser);

The or() and object() combinators aren't just for mutually exclusive options. Subcommands can be implemented using the same principle. Let me introduce the command() parser that matches a single command and the argument() parser that matches positional arguments:

const parser = command(
  "download",
  object({
    targetDirectory: optional(
      option(
        "-t", "--target",
        file({ metavar: "DIR", type: "directory" })
      )
    ),
    urls: multiple(argument(url())),
  })
)

This parser matches commands like:

prog download --target=out/ https://example.com/ https://example.net/

The parser's result type is:

const result: {
  readonly targetDirectory: string | undefined;
  readonly urls: readonly URL[];
} = run(parser);

How would we add an upload subcommand here? That's right, we connect them with the or() combinator:

const parser = or(
  command(
    "download",
    object({
      action: constant("download"),
      targetDirectory: optional(
        option(
          "-t", "--target",
          file({ metavar: "DIR", type: "directory" })
        )
      ),
      urls: multiple(argument(url())),
    })
  ),
  command(
    "upload",
    object({
      action: constant("upload"),
      url: option("-d", "--dest", "--destination", url()),
      files: multiple(
        argument(file({ metavar: "FILE", type: "file" })),
        { min: 1 },
      ),
    })
  ),
);

This parser can now accept commands like:

prog upload ./a.txt ./b.txt -d https://example.com/
prog download -t ./out/ https://example.com/ https://hackers.pub/

The parser's result type is:

const result:
  | {
      readonly action: "download";
      readonly targetDirectory: string | undefined;
      readonly urls: readonly URL[];
    }
  | {
      readonly action: "upload";
      readonly url: URL;
      readonly files: readonly string[];
    }
  = run(parser);

The same approach can be applied to implement nested subcommands, right?

So I've shown you how Optique expresses CLIs. What do you think? Does Optique's approach seem suitable for expressing complex CLIs?

Of course, Optique's approach isn't perfect. It does require more work to define very typical and simple CLIs. Also, since Optique only serves as a CLI parser, it doesn't provide many of the features that general CLI application frameworks offer. (Though I do plan to add more features to Optique in the future…)

If you're still interested in Optique's approach, please check out the introduction documentation and tutorial.

Fedify 1.3.0: OpenTelemetry support & enhanced message queue

Hong Minhee — Sat, 30 Nov 2024 03:50:41 +0000

We're excited to announce the release of Fedify 1.3.0, bringing significant improvements in observability, message queue configuration, and developer experience. This version introduces several new features and enhancements that make it easier to build and monitor federated server applications.

OpenTelemetry integration

The headline feature of this release is comprehensive OpenTelemetry support. Fedify now automatically instruments various operations with OpenTelemetry spans, providing detailed insights into your application's behavior. This feature enables you to:

Track HTTP requests and responses with detailed timing information
Monitor actor and collection dispatching
Observe inbox and outbox operations
Analyze signature verification processes
And much more!

Setting up OpenTelemetry in your Fedify application is straightforward. Once you configure the OpenTelemetry SDK, Fedify automatically creates spans for various operations. Here's a quick example:

import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";

const sdk = new NodeSDK({
  serviceName: "my-fedify-app",
  traceExporter: new OTLPTraceExporter({
    url: "http://localhost:4317",
  }),
});

sdk.start();

You can also integrate with Sentry's OpenTelemetry support:

import { createFederation } from "@fedify/fedify";
import { getClient } from "@sentry/node";

const federation = createFederation({
  tracerProvider: getClient()?.traceProvider,
  // ... other options
});

Note that Sentry's OpenTelemetry integration is available since @sentry/node 8.0.0, but it's not yet available in @sentry/deno or @sentry/bun as of November 2024.

For a complete list of instrumented spans and their attributes, check out our OpenTelemetry documentation.

Enhanced message queue configuration

Fedify 1.3.0 introduces the ability to configure different message queues for incoming and outgoing activities. This feature provides greater flexibility in handling different types of activities. You can:

Use different message queues for incoming and outgoing activities
Use a message queue only for incoming activities
Use a message queue only for outgoing activities
Or any combination thereof

Here are some configuration examples:

Using different queues for incoming and outgoing activities:

import { createFederation } from "@fedify/fedify";
import { RedisMessageQueue } from "@fedify/redis";
import { PostgresMessageQueue } from "@fedify/postgres";

const federation = createFederation({
  queue: {
    inbox: new PostgresMessageQueue(postgres("postgresql://...")),
    outbox: new RedisMessageQueue(redis),
  },
  // ... other options
});

Using a message queue only for incoming activities:

const federation = createFederation({
  queue: {
    inbox: new PostgresMessageQueue(postgres("postgresql://...")),
    // outbox is not provided; outgoing activities will not be queued
  },
  // ... other options
});

Manual activity routing

You can now manually route activities to inbox listeners without requiring an actual HTTP request. This is particularly useful when you need to process an Activity object enclosed within another Activity. For example:

federation.setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Announce, async (ctx, announce) => {
    const object = await announce.getObject();
    if (object instanceof Activity) {
      // Route the enclosed activity to the appropriate inbox listener
      await ctx.routeActivity(ctx.recipient, object);
    }
  });

For details, see also the related documentation.

SvelteKit integration

Thanks to the contribution from Jiyu Park (@robin_maki@planet.moe), Fedify now officially supports SvelteKit through the new @fedify/fedify/x/sveltekit module. This integration makes it easier to build federated applications with SvelteKit:

import { createFederation } from "@fedify/fedify";
import { fedifyHook } from "@fedify/fedify/x/sveltekit";

const federation = createFederation({
  // ... your configuration
});

export const handle = fedifyHook(federation, (req) => "context data");

For details, see also the related documentation.

Better HTTP request identification

Fedify now includes proper User-Agent headers in all HTTP requests it makes. This makes it easier to identify and track Fedify-generated requests in server logs. The default format is:

Fedify/1.3.0 (Deno/2.1.2)

You can customize this by providing your own user agent string or options:

createFederation({
  userAgent: {
    software: "MyApp/1.0.0",
    url: "https://myinstance.com/"
  },
  // ... other options
});

Other improvements

Context.sendActivity() and InboxContext.forwardActivity() methods now properly reject when they fail to enqueue tasks
Various bug fixes and performance improvements
Enhanced documentation and examples

Upgrading to 1.3.0

Fedify 1.3.0 is available on both JSR and npm. To upgrade:

For JSR (Deno):

deno add jsr:@fedify/fedify@1.3.0

For npm (Node.js and Bun):

npm  add @fedify/fedify@1.3.0
pnpm add @fedify/fedify@1.3.0
yarn add @fedify/fedify@1.3.0
bun  add @fedify/fedify@1.3.0

Looking forward

We're excited about these new features and improvements, and we believe they'll make building federated applications with Fedify even more enjoyable. Stay tuned for more updates, and don't hesitate to join our Matrix chat or Discord server if you have any questions or feedback!

For a complete list of changes, check out our changelog.

Hidden Gems of the Fedify CLI: Tips & Tricks You Might Have Missed

Hong Minhee — Fri, 22 Nov 2024 14:59:19 +0000

While Fedify is primarily known as a framework for building ActivityPub servers, it also comes with a powerful command-line tool called fedify for debugging and testing ActivityPub implementations. Whether you're using the Fedify framework or not, this CLI tool can be invaluable for ActivityPub development.

Installation

Before diving into the features, you'll need to install the fedify command. You have several options:

Using npm (Node.js):

npm install -g @fedify/cli

Using Bun:

bun install -g @fedify/cli

Using Deno:

deno install -A --unstable-fs --unstable-kv --unstable-temporal -n fedify jsr:@fedify/cli

You can also download pre-built executables from the releases page.

For more detailed installation instructions and requirements, see the official documentation.

Smart Object Lookup

The fedify lookup command is smarter than it looks—it can handle various formats of the same identifier and provides multiple output formats to suit your needs:

# Three equivalent ways to look up the same actor:
fedify lookup @user@example.com
fedify lookup user@example.com
fedify lookup acct:user@example.com

# View the raw JSON response:
fedify lookup --raw @user@example.com

# Get a compact JSON-LD representation:
fedify lookup --compact @user@example.com

# See the fully expanded JSON-LD:
fedify lookup --expanded @user@example.com

Some ActivityPub servers require authorized fetch (also known as “secure mode”), which means all HTTP GET requests must be signed—even for public content. The -a/--authorized-fetch flag helps with this:

fedify lookup --authorized-fetch @user@secure-instance.example

This spins up a temporary ActivityPub server and signs the request with its key. This is particularly useful when:

Accessing servers that require signatures for all requests (like certain Mastodon instances in secure mode)
Fetching non-public content like followers-only posts (assuming you have permission)
Testing how your server behaves with signed requests

Interactive Inbox Testing

The fedify inbox command not only provides a quick way to test federation but also comes with a powerful web interface for inspecting incoming ActivityPub activities. When you receive an activity, it shows you everything about the request, including:

HTTP method and headers
Request body (in multiple formats)
Response details
Server logs

You can see the raw HTTP headers that other servers send, which is invaluable when debugging signature verification issues or content negotiation problems. The interface includes tabs for viewing the activity in different formats:

Raw HTTP request/response
Compact Activity (normalized JSON-LD)
Expanded Activity (fully expanded JSON-LD)
Raw Activity (as received)
Server logs

The command is highly configurable—you can control which follow requests to accept:

# Only accept follows from specific actors
fedify inbox -a @specific@user.com -a @another@user.com

# Accept all follow requests
fedify inbox -a "*"

Rich NodeInfo Visualization

The fedify node command helps you understand how other instances are configured by visualizing their NodeInfo data in a user-friendly format:

# Show standard NodeInfo data with server icon
fedify node mastodon.social

# Include extra metadata that instances expose
fedify node -m mastodon.social

# Try to parse non-compliant NodeInfo responses
fedify node --best-effort problematic-instance.social

# Skip favicon fetching for faster results
fedify node --no-favicon mastodon.social

Flexible Local Development

For testing your ActivityPub implementation locally, the fedify tunnel command lets you temporarily expose your local server to the internet. You can choose from multiple tunneling services if the default one isn't working well:

# Use the default service
fedify tunnel 3000

# Use an alternative service
fedify tunnel --service serveo.net 3000

Shell Integration

Save yourself some typing by enabling shell completions—available for bash, fish, and zsh:

# For bash
source <(fedify completions bash)

# For fish
source (fedify completions fish | psub)

# For zsh
source <(fedify completions zsh)

Coming in Fedify 1.3.0: Custom `User-Agent` Support

The upcoming Fedify 1.3.0 release will include a feature to set custom User-Agent headers, which is helpful for tracking your requests in server logs:

# Set a custom User-Agent for lookup
fedify lookup --user-agent "MyApp/1.0" @user@example.com

# Set a custom User-Agent for NodeInfo requests
fedify node --user-agent "MyApp/1.0" mastodon.social

These features might not be immediately obvious when you first start using the Fedify CLI, but they can be incredibly helpful when debugging federation issues or testing your ActivityPub implementation.

Introducing implicit contexts in LogTape 0.7.0

Hong Minhee — Tue, 29 Oct 2024 12:17:50 +0000

I'm excited to announce the release of LogTape 0.7.0, which introduces implicit contexts—a powerful new feature that makes it easier than ever to add contextual information to your logs across your entire application.

What are implicit contexts?

Imagine you're handling an HTTP request in your application. You want every log message generated during the request processing to include the request ID, regardless of where in your codebase the log is created. Before implicit contexts, you would need to:

Pass the request ID through every function call
Create a new logger with context for each module
Or use global variables (which have their own problems)

With implicit contexts, you can now set context at the beginning of your request handler, and every log message within that execution context will automatically include that information. Here's a simple example:

function handleRequest(requestId: string) {
  withContext({ requestId }, () => {
    // Any log message in this function or any function it calls
    // will automatically include the requestId
    processRequest();
  });
}

function processRequest() {
  // Note that we don't need to pass the requestId explicitly
  getLogger("processor").info(
    "Processing request: {requestId}"
  );
}

How does it work?

Implicit contexts use the underlying runtime's context-local storage mechanisms (like Node.js's AsyncLocalStorage) to maintain contextual information throughout the execution of your code. This means the context is properly maintained even across asynchronous operations.

To enable implicit contexts in your application, you need to configure LogTape with a context-local storage:

import { AsyncLocalStorage } from "node:async_hooks";
import { configure } from "@logtape/logtape";

await configure({
  // ... other settings ...
  contextLocalStorage: new AsyncLocalStorage(),
});

Nested contexts and priority

One of the powerful features of implicit contexts is that they can be nested. When you nest contexts, the inner context inherits and can override values from the outer context:

function handleRequest(requestId: string) {
  withContext({ requestId, stage: "request" }, () => {
    // stage is "request" here
    processUser(1234);
  });
}

function processUser(userId: number) {
  withContext({ userId, stage: "user" }, () => {
    // stage is "user" here, but requestId is still available
    getLogger("processor").info(
      "Processing user: {userId} for request: {requestId}"
    );
  });
}

When it comes to resolving context values, LogTape follows a clear priority order:

Explicit properties in the log message take highest priority
Explicit context set via Logger.with() takes second priority
Implicit context set via withContext() takes lowest priority

Runtime support

As of October 2024, implicit contexts are supported in:

Node.js
Deno
Bun

Web browsers don't yet support implicit contexts, as they await the implementation of the TC39 Async Context proposal.

Use cases

Implicit contexts are particularly valuable for:

Request Tracing: Add request IDs, user IDs, or session IDs to all logs within a request
Transaction Monitoring: Track transaction IDs across multiple operations
Error Context: Ensure error logs always have relevant contextual information
Performance Monitoring: Add timing information across multiple operations
Tenant Context: In multi-tenant applications, track tenant information across all operations

Best practices

When using implicit contexts, consider these best practices:

Use implicit contexts for information that truly belongs to the entire execution context
Keep context data lightweight—remember it's carried through the entire execution
Use meaningful, consistent key names across your application
Consider using TypeScript to ensure context structure consistency
Document the expected context structure for your application

Migration Guide

If you're already using LogTape, upgrading to use implicit contexts is straightforward:

Update to LogTape 0.7.0
Add context-local storage to your LogTape configuration
Identify places where context is being manually passed around
Replace with withContext() calls at appropriate boundaries

Conclusion

Implicit contexts in LogTape 0.7.0 provide a powerful way to add contextual information to your logs without cluttering your code or manually passing context through your call stack. They're especially valuable in web services, APIs, and other applications where tracking context across operations is important.

I'm excited to see how you'll use this feature to improve your application's logging and observability. Give it a try and let me know what you think!

For more information, check out the complete documentation on implicit contexts.

Fedify, an ActivityPub server framework, reached v1.0.0

Hong Minhee — Wed, 25 Sep 2024 22:34:03 +0000

Fedify, an ActivityPub framework, has finally released its first stable version, 1.0.0!

What is Fedify?

Fedify is a TypeScript library that makes it easy to create federated server applications based on the ActivityPub protocol. ActivityPub is an open standard protocol that allows social networking services to communicate with each other, enabling users to interact across various services in a decentralized social network called the fediverse.

Using Fedify, developers can easily build federated server apps through high-level APIs without having to implement the complex details of the ActivityPub protocol themselves. Fedify provides many features necessary for ActivityPub implementation out of the box, including type-safe interfaces for ActivityPub objects, WebFinger, HTTP Signatures, Linked Data Signatures, and Object Integrity Proofs.

Furthermore, Fedify includes special handling for interoperability with popular fediverse software like Mastodon or Meta's Threads, allowing developers to create applications that can easily integrate with the existing fediverse ecosystem. Additionally, it supports integration with various web frameworks and provides CLI tools, making the development and debugging process even more convenient.

Key changes

Deprecation of the term handle

From this version, the term handle across Fedify will only be used to refer to fediverse handles (e.g., @hongminhee@fosstodon.org). An actor's internal unique ID (e.g., b379dbdc-3b4f-4ef4-88c2-fc25632d1c22) is referred to as an identifier, and the WebFinger name (e.g., hongminhee) is referred to as a username.

The term handle in the API will be maintained for a while for backward compatibility, but deprecation warnings will be logged, and it is planned to be removed in the future.

For more details, please refer to the related documentation.

Linked Data Signatures

Linked Data Signatures is an outdated standard, but it's still relied upon by major fediverse implementations such as Mastodon.

In addition to HTTP Signatures and Object Integrity Proofs, Fedify now supports Linked Data Signatures from this version, thus supporting all types of signature methods used in the fediverse. This makes Fedify an ActivityPub implementation with the best interoperability.

However, Fedify users don't need to do anything special to use Linked Data Signatures. If an incoming activity has Linked Data Signatures, it automatically verifies the signature, and all outgoing activities will have signatures in three formats: HTTP Signatures, Linked Data Signatures, and Object Integrity Proofs.

For more details, please refer to the related documentation.

Activity forwarding

From this version, you can forward activities received in the inbox to other actors using the InboxContext.forwardActivity() method.

At first glance, you might think that you could just resend an activity received in the inbox using the Context.sendActivity() method. However, if you do this, the original signature is removed before the activity is delivered to the inbox, and when sending it, the signature of the forwarding actor is attached instead, causing the receiving side of the forwarded activity to not trust it.

On the other hand, when using the InboxContext.forwardActivity() method, the activity is forwarded with the original signature preserved, avoiding this problem. (Of course, the original activity itself must be signed with Linked Data Signatures or Object Integrity Proofs.)

For more details, please refer to the related documentation.

Sending `Delete(Application)` on `fedify inbox` termination

From this version, fedify inbox will send a Delete(Application) activity to all peer servers it encountered when terminated. This is typically an activity sent when deleting an account, which will help prevent residual data related to temporary actors from remaining on other servers.

PostgreSQL drivers

The @fedify/postgres package, which implements PostgreSQL drivers for the KvStore and MessageQueue interfaces, has been released alongside this version.

The PostgreSQL driver is a backend that can be sufficiently used in production, especially recommended for projects already using PostgreSQL.

Additionally, an option to select the PostgreSQL driver has been added to the fedify init command.

Celebrating Fedify 1.0.0

With the release of version 1.0.0, Fedify will now maintain API backward compatibility as much as possible. (Of course, in the long term, there may be a 2.0.0 that breaks backward compatibility.) This should be good news for those who have been hesitant to use Fedify because there hasn't been a stable version until now!

Fedify 1.0.0 is now available at JSR & npm:

deno add jsr:@fedify/fedify
npm  add     @fedify/fedify

So, hoping that more services will support ActivityPub in the future, I conclude this post!

LogTape 0.6.0 released: What's new?

Hong Minhee — Tue, 24 Sep 2024 08:01:35 +0000

LogTape, a zero-dependency structured logging library for JavaScript and TypeScript, has released v0.6.0. What has changed?

Overriding parent logger's sinks

One of LogTape's features is inheritance of sinks through hierarchical categories. For example, if you set up two loggers like this:

import { configure, getConsoleSink, getFileSink } from "@logtape/logtape";

await configure({
  sinks: {
    console: getConsoleSink(),
    file:    getFileSink("app.log"),
  },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"] },
  ],
});

Logs written to the ["app"] logger will only be saved to the app.log file, but logs written to the ["app", "module"] logger will be saved to both the app.log file and output to the console. This is because the ["app", "module"] logger inherits the sinks from its parent category ["app"].

However, sometimes you might not want this behavior. Starting from LogTape 0.6.0, you can now override the parent logger's sinks. For example, if you enable the parentSinks: "override" option for the child logger like this:

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

Logs written to the ["app"] logger will only be saved to the app.log file, and logs written to the ["app", "module"] logger will only be output to the console. This is because the child logger ["app", "module"] has overridden the sinks of the ["app"] logger.

Of course, the default value is parentSinks: "inherit", so if you don't specify the option, it will behave as before.

If you're curious about the background of this feature addition, please refer to GitHub issue #15.

Allow leading/trailing spaces for placeholders in message templates

In previous versions, if you logged like this:

logger.info("Hello, { name }!", { name: "Alice" });

Contrary to expectations, a log of Hello, undefined! would be created. This was because the placeholder { name } included space characters, so it looked for a property " name " instead of "name". In other words, you had to either remove the spaces from the placeholder like this:

logger.info("Hello, {name}!", { name: "Alice" });

Or add the same spaces to the actual property name like this:

logger.info("Hello, { name }!", { " name ": "Alice" });

While this wasn't strictly a bug, it was behavior prone to mistakes depending on coding habits.

However, starting from LogTape 0.6.0, even if there are spaces at the beginning and end of the placeholder, it will look for a property name without spaces. For example, if you log like this:

logger.info("Hello, { name }!", { name: "Alice" });

As expected, a log of Hello, Alice! will be created.

However, if there is a property that exactly matches including the space characters, that will be prioritized. For example, if you log like this:

logger.info("Hello, { name }!", { name: "Alice", " name ": "Bob" });

Hello, Bob! will be logged instead of Hello, Alice!.

If you're curious about the background of this feature addition, please refer to GitHub issue #16.

`LogRecord.rawMessage` property

LogRecord is a data type that represents a log before it is output and formatted by LogTape.

While the LogRecord.message property already existed, this property contained the result after the placeholders in the message template had been replaced with actual property values. This was sufficient in most cases, but when the log output destination (sink) is another logging system, you might want to output the original message template and property values separately, allowing the receiving logging system to replace the placeholders in the message template with property values directly.

The LogRecord.rawMessage added in LogTape 0.6.0 is a property for exactly this purpose, containing the original state of the message template with placeholders unreplaced. For example, if you log like this:

logger.info("Hello, {name}!", { name: "Alice" });

While LogRecord.message will contain the value ["Hello, ", "Alice", "!"], LogRecord.rawMessage will contain the value "Hello, {name}!".

If you're curious about the background of this feature addition, please refer to GitHub issue #17.

Customizable built-in text formatters

A text formatter is an interface that determines how each log will be formatted into text in stream sinks, file sinks, etc. The actual type definition is quite simple:

export type TextFormatter = (record: LogRecord) => string;

However, it can be cumbersome to define a text formatter directly every time, so LogTape has built-in defaultTextFormatter and ansiColorFormatter that you can use. Until now, because no additional configuration was possible, you had to accept the predetermined format as is. For example, if you didn't like that log levels like "warning" were output as three-letter abbreviations like WRN, you had to implement TextFormatter from scratch.

However, starting from LogTape 0.6.0, you can customize various formatting settings to your liking through the getDefaultTextFormatter() and getAnsiColorFormatter() functions without having to implement TextFormatter from scratch.

For example, if you want to represent log levels like "warning" as a single uppercase letter W, you can configure it like this:

const myFormatter = getDefaultTextFormatter({ level: "L" });

Or if you want to omit the date and timezone from the timestamp and only show the time, you can configure it like this:

const myFormatter = getDefaultTextFormatter({ timestamp: "time" });

For descriptions of more formatting options, please refer to the related documentation.

If you're curious about the background of this feature addition, please refer to GitHub issue #13.

Get it from JSR and npm

LogTape 0.6.0 is already available on JSR and npm, so get it now!

deno add @logtape/logtape@0.6.0  # Deno
npm  add @logtape/logtape@0.6.0  # npm
pnpm add @logtape/logtape@0.6.0  # pnpm
yarn add @logtape/logtape@0.6.0  # Yarn
bun  add @logtape/logtape@0.6.0  # Bun

Happy logging!

LogTape: Zero-Dependency Logging for JavaScript That Just Works

Hong Minhee — Fri, 16 Aug 2024 03:25:24 +0000

Hey there, fellow developers! 👋 Are you tired of wrestling with complex logging libraries that seem to have more dependencies than your entire project? Do you dream of a logging solution that's as easy to use as it is powerful? Well, grab your favorite beverage and get comfortable, because I'm about to introduce you to LogTape—the logging library that's about to make your life a whole lot easier!

What's LogTape?

LogTape is a shiny new logging library for JavaScript and TypeScript that's designed with one goal in mind: to make logging simple, flexible, and hassle-free across all your JavaScript environments. Whether you're building applications for Deno, Node.js, Bun, edge functions, or browsers, LogTape has got you covered.

Why Should You Care?

Let's face it, logging is one of those things that every project needs, but it's rarely the star of the show. That's where LogTape comes in—it handles all the nitty-gritty details of logging so you can focus on what really matters: writing awesome code.

Here's why LogTape deserves a spot in your toolkit:

Zero Dependencies: That's right, zero. Nada. Zilch. LogTape stands on its own two feet, which means no more dependency hell for you!
Runtime Diversity: Use the same logging code everywhere. Deno, Node.js, Bun, edge functions, browsers—LogTape plays nice with all of them.
Structured Logging: Log messages with structured data for easy parsing and analysis.
Hierarchical Categories: Organize your logs with a hierarchical category system, giving you fine-grained control over log verbosity.
Template Literals Support: Use familiar template literals for your log messages. It's as easy as:
```
 logger.info`Hello, ${username}! Welcome to LogTape.`;
```
Dead Simple Sinks: Want to add your own custom log destination? LogTape makes it a breeze!

Show Me the Code!

Alright, let's see LogTape in action. First, you'll need to set it up (don't worry, it's super easy):

import { configure, getConsoleSink } from "@logtape/logtape";

await configure({
  sinks: { console: getConsoleSink() },
  filters: {},
  loggers: [
    { category: "my-awesome-app", level: "debug", sinks: ["console"] }
  ]
});

Now, let's do some logging:

import { getLogger } from "@logtape/logtape";

const logger = getLogger(["my-awesome-app", "user-service"]);

export function greetUser(username: string): void {
  logger.debug`Preparing to greet ${username}`;
  logger.info`Hello, ${username}! Welcome to our awesome app.`;
}

That's it! Clean, simple, and powerful logging at your fingertips.

But Wait, There's More!

LogTape isn't just about basic logging. It's packed with features that make it stand out:

Flexible Sink System: Log to the console, files, or even create your own custom sinks.
Rotating File Logs: Automatically rotate log files to keep things tidy.
Fine-grained Filtering: Control exactly what gets logged and where.
Performance-minded: Lazy evaluation options for when you need to log expensive computations.

Getting Started

Ready to give LogTape a spin? It's as easy as:

For Deno:

deno add jsr:@logtape/logtape

For Node.js:

npm add @logtape/logtape

For Bun:

bun add @logtape/logtape

Wrapping Up

LogTape is the logging library you've been waiting for—simple enough for quick projects, powerful enough for complex applications, and flexible enough to grow with your needs. It's time to say goodbye to logging headaches and hello to LogTape!

Give it a try, and let us know what you think. Happy logging, everyone! 🎉📝

Have you tried LogTape yet? What's your favorite feature? Let us know in the comments below!

DEV Community: Hong Minhee

Your CLI's completion should know what options you've already typed

Static dependencies with or()

Runtime dependencies

The dependency system

Repository-aware completion with @optique/git

Multiple dependencies

Async support

Wrapping up

Building CLI apps with TypeScript in 2026

The naïve approach: parsing process.argv

The traditional libraries

Enter Optique

Building up: a file converter

Mutually exclusive options

Subcommands

Shell completion

Integrating with validation libraries

Tips

Going further

That's it

Designing type-safe sync/async mode support in TypeScript

What is Optique?

How it started

What I needed to solve

Five design options

Option A: conditional types with mode parameter

Option B: mode parameter with default value

Option C: separate interfaces

Option D: union return types for suggest() only

Option E: fp-ts style HKT simulation

Testing the idea

How CombineModes works

Runtime implementation

Refining the API

Creating async value parsers

What it cost

Lessons learned

Listen to users, but validate with prototypes

Backward compatibility is worth the complexity

Unified mode vs per-method granularity

Designing in public

Conclusion

Logging in Node.js (or Deno or Bun or edge functions) in 2026

Starting with console methods—and where they fall short

What you actually need from a logging system

Log levels with filtering

Categories

Sinks (multiple output destinations)

Structured logging

Context for request tracing

Getting started with LogTape

Categories and filtering: Controlling log verbosity

Controlling third-party library logs

The root logger

Log levels and when to use them

Structured logging: Beyond plain text

Template literals (great for simple messages)

Message templates with properties (great for structured data)

Nested property access

Machine-readable output with JSON Lines

Sending logs to different destinations (sinks)

Console sink

File sink

External services

Multiple sinks

Custom sinks

Request tracing with contexts

Explicit context

Implicit context

Framework integrations

Using LogTape in libraries vs applications

If you're writing a library

If you're writing an application

Migrating from another logger?

Production considerations

Non-blocking mode

Sensitive data redaction

Edge functions and serverless

Wrapping up

Static dependencies with `or()`

Repository-aware completion with `@optique/git`

The naïve approach: parsing `process.argv`

How `CombineModes` works

Pro tip: automatic resource cleanup with `await using`

The wrong way: looping with `send()`

The right way: using `sendMany()`

When to use `send()` vs `sendMany()`

Part 8: Provider failover with `PoolTransport`

Coming in Fedify 1.3.0: Custom `User-Agent` Support