When I started building Fedify, an ActivityPub server framework, I ran into a problem that surprised me: I couldn't figure out how to add logging.

Not because logging is hard—there are dozens of mature logging libraries for JavaScript. The problem was that they're primarily designed for applications, not for libraries that want to stay unobtrusive.

I wrote about this a few months ago, and the response was modest—some interest, some skepticism, and quite a bit of debate about whether the post was AI-generated. I'll be honest: English isn't my first language, so I use LLMs to polish my writing. But the ideas and technical content are mine.

Several readers wanted to see a real-world example rather than theory.

The problem: existing loggers assume you're building an app

Fedify helps developers build federated social applications using the ActivityPub protocol. If you've ever worked with federation, you know debugging can be painful. When an activity fails to deliver, you need to answer questions like:

• Did the HTTP request actually go out?
• Was the signature generated correctly?
• Did the remote server reject it? Why?
• Was there a problem parsing the response?

These questions span multiple subsystems: HTTP handling, cryptographic signatures, JSON-LD processing, queue management, and more. Without good logging, debugging turns into guesswork.

But here's the dilemma I faced as a library author: if I add verbose logging to help with debugging, I risk annoying users who don't want their console cluttered with Fedify's internal chatter. If I stay silent, users struggle to diagnose issues.

I looked at the existing options. With winston or Pino, I would have to either:

• Configure a logger inside Fedify (imposing my choices on users), or
• Ask users to pass a logger instance to Fedify (adding boilerplate)

There's also debug, which is designed for this use case. But it doesn't give you structured, level-based logs that ops teams expect—and it relies on environment variables, which some runtimes like Deno restrict by default for security reasons.

None of these felt right. So I built LogTape—a logging library designed from the ground up for library authors. And Fedify became its first real user.

The solution: hierarchical categories with zero default output

The key insight was simple: a library should be able to log without producing any output unless the application developer explicitly enables it.

Fedify uses LogTape's hierarchical category system to give users fine-grained control over what they see. Here's how the categories are organized:

…and about a dozen more. Each category corresponds to a distinct subsystem.

This means a user can configure logging like this:

await configure({
 sinks: { console: getConsoleSink() },
 loggers: [
 // Show errors from all of Fedify
 { category: "fedify", sinks: ["console"], lowestLevel: "error" },
 // But show debug info for inbox processing specifically
 { category: ["fedify", "federation", "inbox"], sinks: ["console"], lowestLevel: "debug" },
 ],
});

When something goes wrong with incoming activities, they get detailed logs for that subsystem while keeping everything else quiet. No code changes required—just configuration.

Request tracing with implicit contexts

The hierarchical categories solved the filtering problem, but there was another challenge: correlating logs across async boundaries.

In a federated system, a single user action might trigger a cascade of operations: fetch a remote actor, verify their signature, process the activity, fan out to followers, and so on. When something fails, you need to correlate all the log entries for that specific request.

Fedify uses LogTape's implicit context feature to automatically tag every log entry with a requestId:

await configure({
 sinks: {
 file: getFileSink("fedify.jsonl", { formatter: jsonLinesFormatter })
 },
 loggers: [
 { category: "fedify", sinks: ["file"], lowestLevel: "info" },
 ],
 contextLocalStorage: new AsyncLocalStorage(), // Enables implicit contexts
});

With this configuration, every log entry automatically includes a requestId property. When you need to debug a specific request, you can filter your logs:

jq 'select(.properties.requestId == "abc-123")' fedify.jsonl

And you'll see every log entry from that request—across all subsystems, all in order. No manual correlation needed.

The requestId is derived from standard headers when available (X-Request-Id, Traceparent, etc.), so it integrates naturally with existing observability infrastructure.

What users actually see

So what does all this configuration actually mean for someone using Fedify?

If a Fedify user doesn't configure LogTape at all, they see nothing. No warnings about missing configuration, no default output, and minimal performance overhead—the logging calls are essentially no-ops.

For basic visibility, they can enable error-level logging for all of Fedify with three lines of configuration. When debugging a specific issue, they can enable debug-level logging for just the relevant subsystem.

And if they're running in production with serious observability requirements, they can pipe structured JSON logs to their monitoring system with request correlation built in.

The same library code supports all these scenarios—whether the user is running on Node.js, Deno, Bun, or edge functions, without extra polyfills or shims. The user decides what they need.

Lessons learned

Building Fedify with LogTape taught me a few things:

Design your categories early. The hierarchical structure should reflect how users will actually want to filter logs. I organized Fedify's categories around subsystems that users might need to debug independently.

Use structured logging. Properties like requestId, activityId, and actorId are far more useful than string interpolation when you need to analyze logs programmatically.

Implicit contexts turned out to be more useful than I expected. Being able to correlate logs across async boundaries without passing context manually made debugging distributed operations much easier. When a user reports that activity delivery failed, I can give them a single jq command to extract everything relevant.

Trust your users. Some library authors worry about exposing too much internal detail through logs. I've found the opposite—users appreciate being able to see what's happening when they need to. The key is making it opt-in.

Try it yourself

If you're building a library and struggling with the logging question—how much to log, how to give users control, how to avoid being noisy—I'd encourage you to look at how Fedify does it.

The Fedify logging documentation explains everything in detail. And if you want to understand the philosophy behind LogTape's design, my earlier post covers that.

LogTape isn't trying to replace winston or Pino for application developers who are happy with those tools. It fills a different gap: logging for libraries that want to stay out of the way until users need them. If that's what you're looking for, it might be a better fit than the usual app-centric loggers.

Fedify, ActivityPub 서버 프레임워크를 개발하기 시작했을 때, 의외의 문제에 부딪혔습니다: 로깅을 추가하는 방법을 찾지 못했습니다.

로깅 자체가 어려워서가 아닙니다—JavaScript용 성숙한 로깅 라이브러리는 수십 개가 있습니다. 문제는 이들이 주로 애플리케이션을 위해 설계되었지, 방해가 되지 않기를 원하는 라이브러리를 위한 것이 아니라는 점이었습니다.

저는 몇 달 전에 이에 대해 글을 썼고, 반응은 소박했습니다—약간의 관심, 약간의 회의론, 그리고 이 글이 AI로 생성되었는지에 대한 꽤 많은 논쟁이 있었습니다. 솔직히 말하자면: 영어는 제 모국어가 아니기 때문에 글을 다듬기 위해 LLM을 사용합니다. 하지만 아이디어와 기술적 내용은 제 것입니다.

몇몇 독자들은 이론보다 실제 사례를 보고 싶어했습니다.

문제: 기존 로거들은 앱을 만든다고 가정합니다

Fedify는 개발자들이 ActivityPub 프로토콜을 사용하여 연합형 소셜 애플리케이션을 구축하는 데 도움을 줍니다. 연합(federation)과 작업해 본 적이 있다면, 디버깅이 얼마나 고통스러울 수 있는지 아실 겁니다. 활동(activity) 전달이 실패했을 때, 다음과 같은 질문에 답해야 합니다:

• HTTP 요청이 실제로 나갔나요?
• 서명이 올바르게 생성되었나요?
• 원격 서버가 이를 거부했나요? 왜 그랬나요?
• 응답 파싱에 문제가 있었나요?

이러한 질문들은 여러 하위 시스템에 걸쳐 있습니다: HTTP 처리, 암호화 서명, JSON-LD 처리, 큐 관리 등. 좋은 로깅 없이는 디버깅이 추측 게임이 됩니다.

하지만 라이브러리 작성자로서 제가 직면한 딜레마는 이것이었습니다: 디버깅을 돕기 위해 상세한 로깅을 추가하면, 콘솔이 Fedify의 내부 잡담으로 어지러워지는 것을 원치 않는 사용자들을 짜증나게 할 위험이 있습니다. 침묵을 지키면, 사용자들은 문제를 진단하는 데 어려움을 겪습니다.

기존 옵션들을 살펴봤습니다. winston이나 Pino를 사용하면 다음 중 하나를 해야 했습니다:

• Fedify 내부에 로거를 구성하거나(사용자에게 내 선택을 강요), 또는
• 사용자에게 로거 인스턴스를 Fedify에 전달하도록 요청(상용구 코드 추가)

또한 debug도 있는데, 이는 이런 사용 사례를 위해 설계되었습니다. 하지만 운영 팀이 기대하는 구조화된, 레벨 기반 로그를 제공하지 않습니다—그리고 환경 변수에 의존하는데, Deno와 같은 일부 런타임은 보안상의 이유로 기본적으로 이를 제한합니다.

이 중 어느 것도 적합하지 않았습니다. 그래서 저는 LogTape—라이브러리 작성자를 위해 처음부터 설계된 로깅 라이브러리를 만들었습니다. 그리고 Fedify는 그 첫 번째 실제 사용자가 되었습니다.

해결책: 기본 출력이 없는 계층적 카테고리

핵심 통찰은 간단했습니다: 라이브러리는 애플리케이션 개발자가 명시적으로 활성화하지 않는 한 어떤 출력도 생성하지 않고 로깅할 수 있어야 합니다.

Fedify는 LogTape의 계층적 카테고리 시스템을 사용하여 사용자에게 보고 싶은 것에 대한 세밀한 제어 권한을 제공합니다. 카테고리는 다음과 같이 구성되어 있습니다:

...그리고 약 십여 개 더 있습니다. 각 카테고리는 별개의 하위 시스템에 해당합니다.

이는 사용자가 다음과 같이 로깅을 구성할 수 있음을 의미합니다:

await configure({
 sinks: { console: getConsoleSink() },
 loggers: [
 // Fedify의 모든 오류 표시
 { category: "fedify", sinks: ["console"], lowestLevel: "error" },
 // 하지만 특별히 inbox 처리에 대한 디버그 정보 표시
 { category: ["fedify", "federation", "inbox"], sinks: ["console"], lowestLevel: "debug" },
 ],
});

수신 활동에 문제가 생기면, 다른 모든 것은 조용히 유지하면서 해당 하위 시스템에 대한 상세한 로그를 얻을 수 있습니다. 코드 변경이 필요 없습니다—단지 구성만 필요합니다.

암시적 컨텍스트를 통한 요청 추적

계층적 카테고리는 필터링 문제를 해결했지만, 또 다른 과제가 있었습니다: 비동기 경계를 넘어 로그를 연관시키는 것입니다.

연합 시스템에서는 단일 사용자 작업이 일련의 작업을 촉발할 수 있습니다: 원격 액터 가져오기, 서명 확인, 활동 처리, 팔로워에게 전파 등. 무언가 실패했을 때, 해당 특정 요청에 대한 모든 로그 항목을 연관시켜야 합니다.

Fedify는 LogTape의 암시적 컨텍스트 기능을 사용하여 모든 로그 항목에 자동으로 requestId를 태그합니다:

await configure({
 sinks: {
 file: getFileSink("fedify.jsonl", { formatter: jsonLinesFormatter })
 },
 loggers: [
 { category: "fedify", sinks: ["file"], lowestLevel: "info" },
 ],
 contextLocalStorage: new AsyncLocalStorage(), // 암시적 컨텍스트 활성화
});

이 구성을 사용하면 모든 로그 항목에 자동으로 requestId 속성이 포함됩니다. 특정 요청을 디버깅해야 할 때 로그를 필터링할 수 있습니다:

jq 'select(.properties.requestId == "abc-123")' fedify.jsonl

그러면 해당 요청의 모든 로그 항목을 볼 수 있습니다—모든 하위 시스템에 걸쳐, 모두 순서대로. 수동 상관관계 분석이 필요 없습니다.

requestId는 가능한 경우 표준 헤더(X-Request-Id, Traceparent 등)에서 파생되므로, 기존 관찰성 인프라와 자연스럽게 통합됩니다.

사용자가 실제로 보는 것

그렇다면 이 모든 구성이 Fedify를 사용하는 사람에게 실제로 어떤 의미가 있을까요?

Fedify 사용자가 LogTape를 전혀 구성하지 않으면, 아무것도 보이지 않습니다. 누락된 구성에 대한 경고도 없고, 기본 출력도 없으며, 성능 오버헤드도 최소화됩니다—로깅 호출은 본질적으로 아무 작업도 하지 않습니다.

기본적인 가시성을 위해, 세 줄의 구성으로 Fedify의 모든 오류 수준 로깅을 활성화할 수 있습니다. 특정 문제를 디버깅할 때는 관련 하위 시스템에 대해서만 디버그 수준 로깅을 활성화할 수 있습니다.

그리고 심각한 관찰성 요구 사항이 있는 프로덕션 환경에서 실행 중이라면, 요청 상관관계가 내장된 구조화된 JSON 로그를 모니터링 시스템으로 전송할 수 있습니다.

동일한 라이브러리 코드가 이 모든 시나리오를 지원합니다—사용자가 Node.js, Deno, Bun 또는 엣지 함수에서 실행하든, 추가 폴리필이나 심(shim) 없이 가능합니다. 사용자가 필요한 것을 결정합니다.

배운 교훈

LogTape로 Fedify를 구축하면서 몇 가지를 배웠습니다:

카테고리를 일찍 설계하세요. 계층적 구조는 사용자가 실제로 로그를 필터링하고 싶어하는 방식을 반영해야 합니다. 저는 Fedify의 카테고리를 사용자가 독립적으로 디버깅해야 할 수 있는 하위 시스템을 중심으로 구성했습니다.

구조화된 로깅을 사용하세요. requestId, activityId, actorId와 같은 속성은 프로그래밍 방식으로 로그를 분석해야 할 때 문자열 보간보다 훨씬 더 유용합니다.

암시적 컨텍스트가 예상보다 더 유용한 것으로 판명되었습니다. 컨텍스트를 수동으로 전달하지 않고도 비동기 경계를 넘어 로그를 연관시킬 수 있어 분산 작업 디버깅이 훨씬 쉬워졌습니다. 사용자가 활동 전달이 실패했다고 보고할 때, 관련된 모든 것을 추출하는 단일 jq 명령을 제공할 수 있습니다.

사용자를 신뢰하세요. 일부 라이브러리 작성자는 로그를 통해 너무 많은 내부 세부 정보를 노출하는 것을 걱정합니다. 저는 반대의 경험을 했습니다—사용자들은 필요할 때 무슨 일이 일어나고 있는지 볼 수 있다는 것을 감사하게 생각합니다. 핵심은 옵트인(opt-in) 방식으로 만드는 것입니다.

직접 시도해 보세요

라이브러리를 구축하면서 로깅 문제—얼마나 많이 로깅할지, 사용자에게 어떻게 제어권을 줄지, 어떻게 시끄럽지 않게 할지—로 고민하고 계시다면, Fedify가 어떻게 하는지 살펴보시길 권장합니다.

Fedify 로깅 문서에서 모든 것을 자세히 설명합니다. 그리고 LogTape 설계 철학을 이해하고 싶다면, 제 이전 글에서 다루고 있습니다.

LogTape은 해당 도구에 만족하는 애플리케이션 개발자를 위해 winston이나 Pino를 대체하려는 것이 아닙니다. 이는 다른 간극을 메웁니다: 사용자가 필요로 할 때까지 방해가 되지 않기를 원하는 라이브러리를 위한 로깅입니다. 그것이 여러분이 찾고 있는 것이라면, 일반적인 앱 중심 로거보다 더 적합할 수 있습니다.

Fedify, ActivityPub 서버 프레임워크를 개발하기 시작했을 때, 의외의 문제에 부딪혔습니다: 로깅을 추가하는 방법을 찾지 못했습니다.

로깅 자체가 어려워서가 아닙니다—JavaScript용 성숙한 로깅 라이브러리는 수십 개가 있습니다. 문제는 이들이 주로 애플리케이션을 위해 설계되었지, 방해가 되지 않기를 원하는 라이브러리를 위한 것이 아니라는 점이었습니다.

저는 몇 달 전에 이에 대해 글을 썼고, 반응은 적당했습니다—약간의 관심, 약간의 회의론, 그리고 이 글이 AI로 생성되었는지에 대한 꽤 많은 논쟁이 있었습니다. 솔직히 말하자면: 영어는 제 모국어가 아니기 때문에 글을 다듬기 위해 LLM을 사용합니다. 하지만 아이디어와 기술적 내용은 제 것입니다.

몇몇 독자들은 이론보다 실제 사례를 보고 싶어했습니다.

문제: 기존 로거들은 앱을 만든다고 가정합니다

Fedify는 개발자들이 ActivityPub 프로토콜을 사용하여 연합형 소셜 애플리케이션을 구축하는 데 도움을 줍니다. 연합(federation)과 작업해 본 적이 있다면, 디버깅이 얼마나 고통스러울 수 있는지 아실 겁니다. 활동(activity) 전달이 실패했을 때, 다음과 같은 질문에 답해야 합니다:

• HTTP 요청이 실제로 나갔나요?
• 서명이 올바르게 생성되었나요?
• 원격 서버가 이를 거부했나요? 왜 그랬나요?
• 응답 파싱에 문제가 있었나요?

이러한 질문들은 여러 하위 시스템에 걸쳐 있습니다: HTTP 처리, 암호화 서명, JSON-LD 처리, 큐 관리 등. 적절한 로깅 없이는 디버깅이 추측 게임이 됩니다.

하지만 라이브러리 작성자로서 제가 직면한 딜레마는 이것이었습니다: 디버깅을 돕기 위해 상세한 로깅을 추가하면, Fedify의 내부 메시지로 콘솔이 어지러워지는 것을 원치 않는 사용자들을 짜증나게 할 위험이 있습니다. 반면 아무 말도 하지 않으면, 사용자들은 문제를 진단하는 데 어려움을 겪습니다.

기존 옵션들을 살펴봤습니다. winston이나 Pino를 사용하면 다음 중 하나를 해야 했습니다:

• Fedify 내부에 로거를 구성하거나(사용자에게 내 선택을 강요), 또는
• 사용자에게 로거 인스턴스를 Fedify에 전달하도록 요청(상용구 코드 추가)

또한 debug도 있는데, 이는 이런 사용 사례를 위해 설계되었습니다. 하지만 운영 팀이 기대하는 구조화된 레벨 기반 로그를 제공하지 않으며, 보안상의 이유로 Deno와 같은 일부 런타임에서 기본적으로 제한하는 환경 변수에 의존합니다.

이 중 어느 것도 적합하지 않았습니다. 그래서 저는 LogTape—라이브러리 작성자를 위해 처음부터 설계된 로깅 라이브러리를 만들었습니다. 그리고 Fedify는 그 첫 번째 실제 사용자가 되었습니다.

해결책: 기본 출력이 없는 계층적 카테고리

핵심 통찰은 간단했습니다: 라이브러리는 애플리케이션 개발자가 명시적으로 활성화하지 않는 한 어떤 출력도 생성하지 않고 로깅할 수 있어야 합니다.

Fedify는 LogTape의 계층적 카테고리 시스템을 사용하여 사용자에게 보고 싶은 것에 대한 세밀한 제어 기능을 제공합니다. 카테고리는 다음과 같이 구성되어 있습니다:

...그리고 약 십여 개 더 있습니다. 각 카테고리는 별개의 하위 시스템에 해당합니다.

이는 사용자가 다음과 같이 로깅을 구성할 수 있음을 의미합니다:

await configure({
 sinks: { console: getConsoleSink() },
 loggers: [
 // Fedify의 모든 오류 표시
 { category: "fedify", sinks: ["console"], lowestLevel: "error" },
 // 하지만 특별히 inbox 처리에 대한 디버그 정보 표시
 { category: ["fedify", "federation", "inbox"], sinks: ["console"], lowestLevel: "debug" },
 ],
});

수신 활동에 문제가 생기면, 다른 모든 것은 조용히 유지하면서 해당 하위 시스템에 대한 상세한 로그를 얻을 수 있습니다. 코드 변경이 필요 없이 구성만으로 가능합니다.

암시적 컨텍스트를 통한 요청 추적

계층적 카테고리는 필터링 문제를 해결했지만, 또 다른 과제가 있었습니다: 비동기 경계를 넘어 로그를 연관시키는 것입니다.

연합 시스템에서는 단일 사용자 작업이 일련의 작업을 촉발할 수 있습니다: 원격 액터 가져오기, 서명 확인, 활동 처리, 팔로워에게 전파 등. 무언가 실패했을 때, 해당 특정 요청에 대한 모든 로그 항목을 연관시켜야 합니다.

Fedify는 LogTape의 암시적 컨텍스트 기능을 사용하여 모든 로그 항목에 자동으로 requestId를 태그합니다:

await configure({
 sinks: {
 file: getFileSink("fedify.jsonl", { formatter: jsonLinesFormatter })
 },
 loggers: [
 { category: "fedify", sinks: ["file"], lowestLevel: "info" },
 ],
 contextLocalStorage: new AsyncLocalStorage(), // 암시적 컨텍스트 활성화
});

이 구성을 통해 모든 로그 항목에는 자동으로 requestId 속성이 포함됩니다. 특정 요청을 디버깅해야 할 때 로그를 필터링할 수 있습니다:

jq 'select(.properties.requestId == "abc-123")' fedify.jsonl

그러면 해당 요청의 모든 로그 항목을 볼 수 있습니다—모든 하위 시스템에 걸쳐, 모두 순서대로. 수동 상관관계 분석이 필요 없습니다.

requestId는 가능한 경우 표준 헤더(X-Request-Id, Traceparent 등)에서 파생되므로 기존 관찰성 인프라와 자연스럽게 통합됩니다.

사용자가 실제로 보는 것

그렇다면 이 모든 구성이 Fedify를 사용하는 사람들에게 실제로 어떤 의미가 있을까요?

Fedify 사용자가 LogTape를 전혀 구성하지 않으면, 아무것도 보이지 않습니다. 누락된 구성에 대한 경고도 없고, 기본 출력도 없으며, 성능 오버헤드도 최소화됩니다—로깅 호출은 본질적으로 아무 작업도 하지 않습니다.

기본적인 가시성을 위해, 세 줄의 구성으로 Fedify의 모든 오류 수준 로깅을 활성화할 수 있습니다. 특정 문제를 디버깅할 때는 관련 하위 시스템에 대해서만 디버그 수준 로깅을 활성화할 수 있습니다.

그리고 심각한 관찰성 요구 사항이 있는 프로덕션 환경에서 실행하는 경우, 요청 상관관계가 내장된 구조화된 JSON 로그를 모니터링 시스템으로 전송할 수 있습니다.

동일한 라이브러리 코드가 이 모든 시나리오를 지원합니다—사용자가 Node.js, Deno, Bun 또는 엣지 함수에서 실행하든, 추가 폴리필이나 심(shim) 없이 가능합니다. 사용자가 필요한 것을 결정합니다.

배운 교훈

LogTape로 Fedify를 구축하면서 몇 가지를 배웠습니다:

카테고리를 일찍 설계하세요. 계층적 구조는 사용자가 실제로 로그를 필터링하고 싶어하는 방식을 반영해야 합니다. 저는 Fedify의 카테고리를 사용자가 독립적으로 디버깅해야 할 수 있는 하위 시스템을 중심으로 구성했습니다.

구조화된 로깅을 사용하세요. requestId, activityId, actorId와 같은 속성은 프로그래밍 방식으로 로그를 분석해야 할 때 문자열 보간보다 훨씬 더 유용합니다.

암시적 컨텍스트는 예상보다 더 유용했습니다. 컨텍스트를 수동으로 전달하지 않고도 비동기 경계를 넘어 로그를 연관시킬 수 있어 분산 작업 디버깅이 훨씬 쉬워졌습니다. 사용자가 활동 전달이 실패했다고 보고할 때, 관련된 모든 것을 추출하는 단일 jq 명령을 제공할 수 있습니다.

사용자를 신뢰하세요. 일부 라이브러리 작성자는 로그를 통해 너무 많은 내부 세부 정보를 노출하는 것을 걱정합니다. 저는 반대의 경험을 했습니다—사용자들은 필요할 때 무슨 일이 일어나고 있는지 볼 수 있다는 것을 감사하게 생각합니다. 핵심은 옵트인(opt-in) 방식으로 만드는 것입니다.

직접 시도해 보세요

라이브러리를 구축하면서 로깅 문제—얼마나 많이 로깅할지, 사용자에게 어떻게 제어권을 줄지, 어떻게 시끄럽지 않게 할지—로 고민하고 계시다면, Fedify가 어떻게 하는지 살펴보시길 권장합니다.

Fedify 로깅 문서에서 모든 것을 자세히 설명합니다. 그리고 LogTape 설계 철학을 이해하고 싶다면, 이전 포스트에서 다루고 있습니다.

LogTape은 winston이나 Pino에 만족하는 애플리케이션 개발자들을 위한 대체품이 되려는 것이 아닙니다. 이는 다른 간극을 메웁니다: 사용자가 필요로 할 때까지 방해가 되지 않기를 원하는 라이브러리를 위한 로깅입니다. 그것이 당신이 찾고 있는 것이라면, 일반적인 앱 중심 로거보다 더 적합할 수 있습니다.

We're excited to announce Optique 0.8.0! This release introduces powerful new features for building sophisticated CLI applications: the conditional() combinator for discriminated union patterns, the passThrough() parser for wrapper tools, and the new @optique/logtape package for seamless logging configuration.

Optique is a type-safe combinatorial CLI parser for TypeScript, providing a functional approach to building command-line interfaces with composable parsers and full type inference.

New conditional parsing with conditional()

Ever needed to enable different sets of options based on a discriminator value? The new conditional() combinator makes this pattern first-class. It creates discriminated unions where certain options only become valid when a specific discriminator value is selected.

import { conditional, object } from "@optique/core/constructs";
import { option } from "@optique/core/primitives";
import { choice, string } from "@optique/core/valueparser";

const parser = conditional(
 option("--reporter", choice(["console", "junit", "html"])),
 {
 console: object({}),
 junit: object({ outputFile: option("--output-file", string()) }),
 html: object({ outputFile: option("--output-file", string()) }),
 }
);
// Result type: ["console", {}] | ["junit", { outputFile: string }] | ...

Key features:

• Explicit discriminator option determines which branch is selected
• Tuple result [discriminator, branchValue] for clear type narrowing
• Optional default branch for when discriminator is not provided
• Clear error messages indicating which options are required for each discriminator value

The conditional() parser provides a more structured alternative to or() for discriminated union patterns. Use it when you have an explicit discriminator option that determines which set of options is valid.

See the conditional() documentation for more details and examples.

Pass-through options with passThrough()

Building wrapper CLI tools that need to forward unrecognized options to an underlying tool? The new passThrough() parser enables legitimate wrapper/proxy patterns by capturing unknown options without validation errors.

import { object } from "@optique/core/constructs";
import { option, passThrough } from "@optique/core/primitives";

const parser = object({
 debug: option("--debug"),
 extra: passThrough(),
});

// mycli --debug --foo=bar --baz=qux
// → { debug: true, extra: ["--foo=bar", "--baz=qux"] }

Key features:

• Three capture formats: "equalsOnly" (default, safest), "nextToken" (captures --opt val pairs), and "greedy" (captures all remaining tokens)
• Lowest priority (−10) ensures explicit parsers always match first
• Respects -- options terminator in "equalsOnly" and "nextToken" modes
• Works seamlessly with object(), subcommands, and other combinators

This feature is designed for building Docker-like CLIs, build tool wrappers, or any tool that proxies commands to another process.

See the passThrough() documentation for usage patterns and best practices.

LogTape logging integration

The new @optique/logtape package provides seamless integration with LogTape, enabling you to configure logging through command-line arguments with various parsing strategies.

# Deno
deno add --jsr @optique/logtape @logtape/logtape

# npm
npm add @optique/logtape @logtape/logtape

Quick start with the loggingOptions() preset:

import { loggingOptions, createLoggingConfig } from "@optique/logtape";
import { object } from "@optique/core/constructs";
import { parse } from "@optique/core/parser";
import { configure } from "@logtape/logtape";

const parser = object({
 logging: loggingOptions({ level: "verbosity" }),
});

const args = ["-vv", "--log-output=-"];
const result = parse(parser, args);
if (result.success) {
 const config = await createLoggingConfig(result.value.logging);
 await configure(config);
}

The package offers multiple approaches to control log verbosity:

• verbosity() parser: The classic -v/-vv/-vvv pattern where each flag increases verbosity (no flags → "warning", -v → "info", -vv → "debug", -vvv → "trace")
• debug() parser: Simple --debug/-d flag that toggles between normal and debug levels
• logLevel() value parser: Explicit --log-level=debug option for direct level selection
• logOutput() parser: Log output destination with - for console or file path for file output

See the LogTape integration documentation for complete examples and configuration options.

Bug fix: negative integers now accepted

Fixed an issue where the integer() value parser rejected negative integers when using type: "number". The regex pattern has been updated from /^\d+$/ to /^-?\d+$/ to correctly handle values like -42. Note that type: "bigint" already accepted negative integers, so this change brings consistency between the two types.

Installation

# Deno
deno add jsr:@optique/core

# npm
npm add @optique/core

# pnpm
pnpm add @optique/core

# Yarn
yarn add @optique/core

# Bun
bun add @optique/core

For the LogTape integration:

# Deno
deno add --jsr @optique/logtape @logtape/logtape

# npm
npm add @optique/logtape @logtape/logtape

# pnpm
pnpm add @optique/logtape @logtape/logtape

# Yarn
yarn add @optique/logtape @logtape/logtape

# Bun
bun add @optique/logtape @logtape/logtape

Looking forward

Optique 0.8.0 continues our focus on making CLI development more expressive and type-safe. The conditional() combinator brings discriminated union patterns to the forefront, passThrough() enables new wrapper tool use cases, and the LogTape integration makes logging configuration a breeze.

As always, all new features maintain full backward compatibility—your existing parsers continue to work unchanged.

We're grateful to the community for feedback and suggestions. If you have ideas for future improvements or encounter any issues, please let us know through GitHub Issues. For more information about Optique and its features, visit the documentation or check out the full changelog.

Optique 0.8.0 출시를 발표하게 되어 기쁩니다! 이번 릴리스는 정교한 CLI 애플리케이션 구축을 위한 강력한 새 기능을 소개합니다: 판별 유니온 패턴을 위한 conditional() 조합기, 래퍼 도구를 위한 passThrough() 파서, 그리고 원활한 로깅 구성을 위한 새로운 @optique/logtape 패키지가 포함되어 있습니다.

Optique는 TypeScript를 위한 타입 안전 조합형 CLI 파서로, 조합 가능한 파서와 완전한 타입 추론을 통해 명령줄 인터페이스를 구축하는 함수형 접근 방식을 제공합니다.

conditional()을 이용한 새로운 조건부 파싱

판별자 값에 따라 다른 옵션 세트를 활성화해야 할 필요가 있었나요? 새로운 conditional() 조합기는 이 패턴을 일급 객체로 만듭니다. 특정 판별자 값이 선택되었을 때만 특정 옵션이 유효해지는 판별 유니온을 생성합니다.

import { conditional, object } from "@optique/core/constructs";
import { option } from "@optique/core/primitives";
import { choice, string } from "@optique/core/valueparser";

const parser = conditional(
 option("--reporter", choice(["console", "junit", "html"])),
 {
 console: object({}),
 junit: object({ outputFile: option("--output-file", string()) }),
 html: object({ outputFile: option("--output-file", string()) }),
 }
);
// Result type: ["console", {}] | ["junit", { outputFile: string }] | ...

주요 기능:

• 명시적 판별자 옵션이 어떤 분기가 선택될지 결정
• 명확한 타입 좁히기를 위한 튜플 결과 [discriminator, branchValue]
• 판별자가 제공되지 않을 때를 위한 선택적 기본 분기
• 각 판별자 값에 필요한 옵션을 명확히 표시하는 오류 메시지

conditional() 파서는 판별 유니온 패턴에 대한 or()의 더 구조화된 대안을 제공합니다. 어떤 옵션 세트가 유효한지 결정하는 명시적 판별자 옵션이 있을 때 사용하세요.

자세한 내용과 예제는 conditional() 문서를 참조하세요.

passThrough()를 이용한 패스스루 옵션

인식되지 않은 옵션을 기본 도구로 전달해야 하는 래퍼 CLI 도구를 구축하고 계신가요? 새로운 passThrough() 파서는 검증 오류 없이 알 수 없는 옵션을 캡처하여 정당한 래퍼/프록시 패턴을 가능하게 합니다.

import { object } from "@optique/core/constructs";
import { option, passThrough } from "@optique/core/primitives";

const parser = object({
 debug: option("--debug"),
 extra: passThrough(),
});

// mycli --debug --foo=bar --baz=qux
// → { debug: true, extra: ["--foo=bar", "--baz=qux"] }

주요 기능:

• 세 가지 캡처 형식: "equalsOnly" (기본값, 가장 안전), "nextToken" (--opt val 쌍 캡처), "greedy" (남은 모든 토큰 캡처)
• 가장 낮은 우선순위(-10)로 명시적 파서가 항상 먼저 일치하도록 보장
• "equalsOnly"와 "nextToken" 모드에서 -- 옵션 종결자 존중
• object(), 서브커맨드 및 기타 조합기와 원활하게 작동

이 기능은 Docker와 같은 CLI, 빌드 도구 래퍼 또는 다른 프로세스에 명령을 프록시하는 모든 도구를 구축하기 위해 설계되었습니다.

사용 패턴과 모범 사례는 passThrough() 문서를 참조하세요.

LogTape 로깅 통합

새로운 @optique/logtape 패키지는 LogTape와의 원활한 통합을 제공하여 다양한 파싱 전략을 통해 명령줄 인수로 로깅을 구성할 수 있게 합니다.

# Deno
deno add --jsr @optique/logtape @logtape/logtape

# npm
npm add @optique/logtape @logtape/logtape

loggingOptions() 프리셋으로 빠르게 시작하기:

import { loggingOptions, createLoggingConfig } from "@optique/logtape";
import { object } from "@optique/core/constructs";
import { parse } from "@optique/core/parser";
import { configure } from "@logtape/logtape";

const parser = object({
 logging: loggingOptions({ level: "verbosity" }),
});

const args = ["-vv", "--log-output=-"];
const result = parse(parser, args);
if (result.success) {
 const config = await createLoggingConfig(result.value.logging);
 await configure(config);
}

이 패키지는 로그 상세도를 제어하기 위한 여러 접근 방식을 제공합니다:

• verbosity() 파서: 각 플래그가 상세도를 높이는 고전적인 -v/-vv/-vvv 패턴 (플래그 없음 → "warning", -v → "info", -vv → "debug", -vvv → "trace")
• debug() 파서: 일반 레벨과 디버그 레벨 사이를 전환하는 간단한 --debug/-d 플래그
• logLevel() 값 파서: 직접 레벨 선택을 위한 명시적 --log-level=debug 옵션
• logOutput() 파서: 콘솔을 위한 - 또는 파일 출력을 위한 파일 경로로 로그 출력 대상 지정

전체 예제와 구성 옵션은 LogTape 통합 문서를 참조하세요.

버그 수정: 음수 정수 이제 허용

type: "number"를 사용할 때 integer() 값 파서가 음수 정수를 거부하는 문제를 수정했습니다. 정규식 패턴이 /^\d+$/에서 /^-?\d+$/로 업데이트되어 -42와 같은 값을 올바르게 처리합니다. type: "bigint"는 이미 음수 정수를 허용했으므로, 이 변경으로 두 타입 간의 일관성이 확보되었습니다.

설치

# Deno
deno add jsr:@optique/core

# npm
npm add @optique/core

# pnpm
pnpm add @optique/core

# Yarn
yarn add @optique/core

# Bun
bun add @optique/core

LogTape 통합을 위한 설치:

# Deno
deno add --jsr @optique/logtape @logtape/logtape

# npm
npm add @optique/logtape @logtape/logtape

# pnpm
pnpm add @optique/logtape @logtape/logtape

# Yarn
yarn add @optique/logtape @logtape/logtape

# Bun
bun add @optique/logtape @logtape/logtape

앞으로의 계획

Optique 0.8.0은 CLI 개발을 더 표현력 있고 타입 안전하게 만드는 데 계속 초점을 맞추고 있습니다. conditional() 조합기는 판별 유니온 패턴을 전면에 내세우고, passThrough()는 새로운 래퍼 도구 사용 사례를 가능하게 하며, LogTape 통합은 로깅 구성을 간편하게 만듭니다.

항상 그렇듯이, 모든 새로운 기능은 완전한 하위 호환성을 유지합니다—기존 파서는 변경 없이 계속 작동합니다.

피드백과 제안을 해주신 커뮤니티에 감사드립니다. 향후 개선 사항에 대한 아이디어가 있거나 문제가 발생하면 GitHub Issues를 통해 알려주세요. Optique와 그 기능에 대한 자세한 정보는 문서를 방문하거나 전체 변경 로그를 확인하세요.

Optique 0.8.0 출시를 발표하게 되어 기쁩니다! 이번 릴리스는 정교한 CLI 애플리케이션을 구축하기 위한 강력한 새 기능을 소개합니다: 판별 유니온 패턴을 위한 conditional() 조합기, 래퍼 도구를 위한 passThrough() 파서, 그리고 원활한 로깅 구성을 위한 새로운 @optique/logtape 패키지가 포함되어 있습니다.

Optique는 TypeScript를 위한 타입 안전 조합형 CLI 파서로, 조합 가능한 파서와 완전한 타입 추론을 통해 명령줄 인터페이스를 구축하는 함수형 접근 방식을 제공합니다.

conditional()을 이용한 새로운 조건부 파싱

판별자 값에 따라 다른 옵션 세트를 활성화해야 할 필요가 있었나요? 새로운 conditional() 조합기는 이 패턴을 일급 객체로 만듭니다. 특정 판별자 값이 선택되었을 때만 특정 옵션이 유효해지는 판별 유니온을 생성합니다.

import { conditional, object } from "@optique/core/constructs";
import { option } from "@optique/core/primitives";
import { choice, string } from "@optique/core/valueparser";

const parser = conditional(
 option("--reporter", choice(["console", "junit", "html"])),
 {
 console: object({}),
 junit: object({ outputFile: option("--output-file", string()) }),
 html: object({ outputFile: option("--output-file", string()) }),
 }
);
// Result type: ["console", {}] | ["junit", { outputFile: string }] | ...

주요 기능:

• 명시적 판별자 옵션이 어떤 분기가 선택될지 결정
• 명확한 타입 좁히기를 위한 튜플 결과 [discriminator, branchValue]
• 판별자가 제공되지 않을 때를 위한 선택적 기본 분기
• 각 판별자 값에 필요한 옵션을 명확히 표시하는 오류 메시지

conditional() 파서는 판별 유니온 패턴에 대한 or()의 더 구조화된 대안을 제공합니다. 어떤 옵션 세트가 유효한지 결정하는 명시적 판별자 옵션이 있을 때 사용하세요.

자세한 내용과 예제는 conditional() 문서를 참조하세요.

passThrough()를 이용한 패스스루 옵션

인식되지 않은 옵션을 기본 도구로 전달해야 하는 래퍼 CLI 도구를 구축하고 계신가요? 새로운 passThrough() 파서는 유효성 검사 오류 없이 알 수 없는 옵션을 캡처하여 정당한 래퍼/프록시 패턴을 가능하게 합니다.

import { object } from "@optique/core/constructs";
import { option, passThrough } from "@optique/core/primitives";

const parser = object({
 debug: option("--debug"),
 extra: passThrough(),
});

// mycli --debug --foo=bar --baz=qux
// → { debug: true, extra: ["--foo=bar", "--baz=qux"] }

주요 기능:

• 세 가지 캡처 형식: "equalsOnly" (기본값, 가장 안전), "nextToken" (--opt val 쌍 캡처), "greedy" (남은 모든 토큰 캡처)
• 가장 낮은 우선순위(-10)로 명시적 파서가 항상 먼저 일치하도록 보장
• "equalsOnly"와 "nextToken" 모드에서 -- 옵션 종결자 존중
• object(), 서브커맨드 및 기타 조합기와 원활하게 작동

이 기능은 Docker와 같은 CLI, 빌드 도구 래퍼 또는 명령을 다른 프로세스로 프록시하는 모든 도구를 구축하기 위해 설계되었습니다.

사용 패턴과 모범 사례는 passThrough() 문서를 참조하세요.

LogTape 로깅 통합

새로운 @optique/logtape 패키지는 LogTape와의 원활한 통합을 제공하여 다양한 파싱 전략을 통해 명령줄 인수로 로깅을 구성할 수 있게 합니다.

# Deno
deno add --jsr @optique/logtape @logtape/logtape

# npm
npm add @optique/logtape @logtape/logtape

loggingOptions() 프리셋을 사용한 빠른 시작:

import { loggingOptions, createLoggingConfig } from "@optique/logtape";
import { object } from "@optique/core/constructs";
import { parse } from "@optique/core/parser";
import { configure } from "@logtape/logtape";

const parser = object({
 logging: loggingOptions({ level: "verbosity" }),
});

const args = ["-vv", "--log-output=-"];
const result = parse(parser, args);
if (result.success) {
 const config = await createLoggingConfig(result.value.logging);
 await configure(config);
}

이 패키지는 로그 상세 수준을 제어하기 위한 여러 접근 방식을 제공합니다:

• verbosity() 파서: 각 플래그가 상세 수준을 높이는 고전적인 -v/-vv/-vvv 패턴 (플래그 없음 → "warning", -v → "info", -vv → "debug", -vvv → "trace")
• debug() 파서: 일반 수준과 디버그 수준 사이를 전환하는 간단한 --debug/-d 플래그
• logLevel() 값 파서: 직접적인 수준 선택을 위한 명시적 --log-level=debug 옵션
• logOutput() 파서: 콘솔을 위한 - 또는 파일 출력을 위한 파일 경로의 로그 출력 대상

전체 예제와 구성 옵션은 LogTape 통합 문서를 참조하세요.

버그 수정: 음수 정수 이제 허용

type: "number"를 사용할 때 integer() 값 파서가 음수 정수를 거부하는 문제가 수정되었습니다. 정규식 패턴이 /^\d+$/에서 /^-?\d+$/로 업데이트되어 -42와 같은 값을 올바르게 처리합니다. type: "bigint"는 이미 음수 정수를 허용했으므로, 이 변경으로 두 타입 간의 일관성이 유지됩니다.

설치

# Deno
deno add jsr:@optique/core

# npm
npm add @optique/core

# pnpm
pnpm add @optique/core

# Yarn
yarn add @optique/core

# Bun
bun add @optique/core

LogTape 통합을 위한 설치:

# Deno
deno add --jsr @optique/logtape @logtape/logtape

# npm
npm add @optique/logtape @logtape/logtape

# pnpm
pnpm add @optique/logtape @logtape/logtape

# Yarn
yarn add @optique/logtape @logtape/logtape

# Bun
bun add @optique/logtape @logtape/logtape

앞으로의 계획

Optique 0.8.0은 CLI 개발을 더 표현력 있고 타입 안전하게 만드는 데 계속 집중하고 있습니다. conditional() 조합기는 판별 유니온 패턴을 전면에 내세우고, passThrough()는 새로운 래퍼 도구 사용 사례를 가능하게 하며, LogTape 통합은 로깅 구성을 쉽게 만듭니다.

항상 그렇듯이, 모든 새로운 기능은 완전한 하위 호환성을 유지합니다—기존 파서는 변경 없이 계속 작동합니다.

피드백과 제안을 해주신 커뮤니티에 감사드립니다. 향후 개선 사항에 대한 아이디어가 있거나 문제가 발생하면 GitHub Issues를 통해 알려주세요. Optique와 그 기능에 대한 자세한 정보는 문서를 방문하거나 전체 변경 로그를 확인하세요.