洪 民憙 (Hong Minhee)'s avatar

洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · 955 following · 1269 followers

An intersectionalist, feminist, and socialist guy living in Seoul (UTC+09:00). @tokolovesme's spouse. Who's behind @fedify, @hollo, and @botkit. Write some free software in , , , & . They/them.

서울에 사는 交叉女性主義者이자 社會主義者. 金剛兔(@tokolovesme)의 配偶者. @fedify, @hollo, @botkit 메인테이너. , , , 等으로 自由 소프트웨어 만듦.

()

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social

Hello, I'm an open source software engineer in my late 30s living in , , and an avid advocate of and the .

I'm the creator of @fedify, an server framework in , @hollo, an ActivityPub-enabled microblogging software for single users, and @botkit, a simple ActivityPub bot framework.

I'm also very interested in East Asian languages (so-called ) and . Feel free to talk to me in , (), or (), or even in Literary Chinese (, )!

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to 洪 民憙 (Hong Minhee)'s post

安寧(안녕)하세요, 저는 서울에 살고 있는 30() 後半(후반) 오픈 소스 소프트웨어 엔지니어이며, 自由(자유)·오픈 소스 소프트웨어와 聯合宇宙(연합우주)(fediverse)의 熱烈(열렬)支持者(지지자)입니다.

저는 TypeScript() ActivityPub 서버 프레임워크인 @fedify 프로젝트와 싱글 유저() ActivityPub 마이크로블로그인 @hollo 프로젝트와 ActivityPub 봇 프레임워크인 @botkit 프로젝트의 製作者(제작자)이기도 합니다.

저는 ()아시아 言語(언어)(이른바 )와 유니코드에도 關心(관심)이 많습니다. 聯合宇宙(연합우주)에서는 國漢文混用體(국한문 혼용체)를 쓰고 있어요! 제게 韓國語(한국어)英語(영어), 日本語(일본어)로 말을 걸어주세요. (아니면, 漢文(한문)으로도!)

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to 洪 民憙 (Hong Minhee)'s post

こんにちは、私はソウルに住んでいる30代後半のオープンソースソフトウェアエンジニアで、自由・オープンソースソフトウェアとフェディバースの熱烈な支持者です。名前は洪 民憙ホン・ミンヒです。

私はTypeScript用のActivityPubサーバーフレームワークである「@fedify」と、ActivityPubをサポートする1人用マイクロブログである 「@hollo」と、ActivityPubのボットを作成する為のシンプルなフレームワークである「@botkit」の作者でもあります。

私は東アジア言語(いわゆるCJK)とUnicodeにも興味が多いです。日本語、英語、韓国語で話しかけてください。(または、漢文でも!)

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social

パーサーコンビネーターという関数型プログラミングの手法をTypeScriptのCLI開発に応用した「Optique」について。型推論を活かして、組み合わせるだけで型安全なCLIが作れます。

https://zenn.dev/hongminhee/articles/904d9c8511a03b

just small circles 🕊's avatar
just small circles 🕊

@smallcircles@social.coop · Reply to wakest ⁂'s post

@liaizon @hongminhee @oeee_cafe @jihyeok

Nice! I've lined this licensed project up to be included in the delightful fediverse experience curated list at..

delightful.coding.social/delig

I found the codebase on github at..

github.com/yangnaru/oeee-cafe

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to Jaeyeol Lee (a.k.a. kodingwarrior) :vim:'s post

@kodingwarrior 커맨드를 어떻게 주셨나요?

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to Jaeyeol Lee (a.k.a. kodingwarrior) :vim:'s post

@kodingwarrior @robin_maki 아, 그건 그쪽에서 Fedify의 User-Agent를 막았을 수도 있어요. -u 옵션으로 User-Agenr를 한 번 바꿔보시면…

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to Jaeyeol Lee (a.k.a. kodingwarrior) :vim:'s post

@kodingwarrior @robin_maki -a/--authorized-fetch 옵션 줘도 안 되나요?

wakest ⁂'s avatar
wakest ⁂

@liaizon@social.wake.st

As @hongminhee recently posted about

A new drawing community called oeee.cafe (@oeee_cafe) made by @jihyeok and others just implemented and joined the . It's exciting to see niche art focused software using these tools and techniques to share in our weird network we have here.

via hollo.social/@hongminhee/0198e

announcement post: hackers.pub/@jihyeok/0198e00f-

wakest ⁂'s avatar
wakest ⁂

@liaizon@social.wake.st · Reply to 洪 民憙 (Hong Minhee)'s post

@hongminhee@hollo.social @jihyeok @hongminhee@oeee.cafe ow wow that amazing, I was just looking at a platform that added support recently, it's interesting to see those nieche communities finding the power of decentralization!

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social

Excited to share some great news from the community! Oeee Cafe, a fantastic oekaki platform, just added support today. This means all the amazing artwork being created there can now be shared and discovered across the , which is such a wonderful step toward connecting creative communities.

Big shoutout to my friend @jihyeok for building this platform and bringing it to the fediverse. It's always inspiring to see developers creating spaces for artists and then opening them up to the broader federated community. If you're into digital art or just appreciate seeing creative work, definitely worth checking out what people are sharing from Oeee Cafe on your timeline now. You can find me there at @hongminhee if you want to connect!

Jihyeok Seo's avatar
Jihyeok Seo

@jihyeok@hackers.pub · Reply to Jihyeok Seo's post

I added ActivityPub support to Oeee Cafe, which is a safe-for-work Oekaki-style drawing board.

You can view the handles for artists or communities you like in the profile or the community main page. Subscribe and get new artwork right in your Fediverse timeline!

Special thanks to @hongminhee who helped me implement ActivityPub. Quoted is his drawing in the early days of Oeee Cafe.



RE: https://oeee.cafe/@hongminhee/ed323b59-557c-4843-aad2-5a83df0e3006

Jihyeok Seo's avatar
Jihyeok Seo

@jihyeok@hackers.pub

오이카페에 ActivityPub 지원이 들어갔습니다. 이제 좋아하는 작가나 커뮤니티의 새 그림을 연합우주에서도 받아 보세요!

작가 프로필이나 커뮤니티 메인 페이지에서 ActivityPub 핸들을 확인할 수 있습니다.

인용된 그림은 ActivityPub 연동을 도와주신 @hongminhee 님이 오이카페 초창기에 그려 주신 고양이 그림입니다. 감사합니다!



RE: https://oeee.cafe/@hongminhee/ed323b59-557c-4843-aad2-5a83df0e3006

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social

@eatch.dev 이 책인가요…?

bgl gwyng's avatar
bgl gwyng

@bgl@hackers.pub

만약 페디버스가 지금보다 훨씬 활성화되어서, 사람들이 커스터마이징된 개성있는 인스턴스를 갖게 되면, 그게 UX의 측면에서 정말로 좋을까요? 가령, 트위터를 하는데 사용자마다 UI가 다르다고 상상해보세요.

사실 저는 크게 부정적이진 않는데(좋은 쪽으로 개성있을수도 있으니까), 그런 상황이 머릿속에서 아주 잘 시뮬레이션 되지 않네요. 어떨거 같나요?

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social

日常(일상)에서 우리가 「知能(지능)」이라는 말을 써야만 하는 일은 그렇게 많지 않고, 그 말을 썼다면 程度(정도)差異(차이)가 있을 뿐 人種主義的(인종주의적) 乃至(내지)優生學的(우생학적)으로 들리는 境遇(경우)가 많다고 느낀다.

geeknews_bot's avatar
geeknews_bot

@geeknews_bot@sns.lemondouble.com

Show GN: Optique: TypeScript를 위한 타입 안전한 CLI 파서
------------------------------
안녕하세요! TypeScript로 CLI 도구를 자주 만들다 보니 기존 라이브러리들의 한계가 아쉬워서 새로운 CLI 파서를 만들게 되었습니다. 혹시 관심 있으신 분들께 소개해보고 싶어 글을 올립니다.

CLI 애플리케이션을 개발하면서 늘 불편했던 점이 하나 있었습니다. 기존 CLI 파서 라이브러리들은 대부분 설정 객체나…
------------------------------
https://news.hada.io/topic?id=22670&utm_source=googlechat&utm_medium=bot&utm_campaign=1834

Renaud Chaput's avatar
Renaud Chaput

@renchap@oisaur.com

Coming soon on your Mastodon server… The long awaited quote posts, with user-control (you can chose if you want to be quoted on a per-post basis, change it later, and retract any quote of your post)

Amazing work by the team 🎉

Expect a blog post with all the details in a few weeks, support in the mobile apps, then we will enable the feature on mastodon.social, then release Mastodon 4.5

Screenshot of the Mastodon composer, showing a new visibility picker button with a "Public, anyone can quote" label
ALT text detailsScreenshot of the Mastodon composer, showing a new visibility picker button with a "Public, anyone can quote" label
洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social

오늘 저녁은 비건 비빔밥.

비건 비빔밥
ALT text details비건 비빔밥
洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hackers.pub

投稿(Note)と記事(Article)の両方でMarkdownをサポートしているだけでなく、シンタックスハイライトとTeX数式にも対応しているという点で、[1]Hackers' Pubはフェディバースで最もソフトウェアプログラマーに適したプラットフォームであると自負しております。

そんな皆さんのために、Hackers' Pubの招待状を共有します。(笑)


  1. ちなみに、Hackers' Pubはかなり多様なMarkdown拡張構文をサポートしています。 ↩︎

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to bgl gwyng's post

@bgl 白手(백수)의 힘입니다! ㅋㅋㅋ

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to 쯔방 :yuri: :yurigarden: :garden:'s post

@pbzweihander 저는 국한문혼용을 쓰고 싶어서 (정확히는 국한문혼용에 자동으로 한글 독음이 붙게 하고 싶어서) Hollo를 만들었는데, 뭔가 그런 식으로 다른 플랫폼에서는 안 넣어줄 것 같은데 원하는 기능은 없으신가요? 그런 게 있으면 동력이 좀 생기더라고요.

David Bushell 🪡's avatar
David Bushell 🪡

@db@social.lol

things LLMs have ruined for bloggers:

* emoji
* the em-dash

and now I'm hearing, the Oxford comma?! Game's gone.

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to 쯔방 :yuri: :yurigarden: :garden:'s post

@pbzweihander 참새 얼른 만드세욧!

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to robin's post

@robin_maki 얼른 Kosmo 만들어 주세요…!

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hackers.pub · Reply to 洪 民憙 (Hong Minhee)'s post

참고로 Hackers' Pub은 꽤 다양한 Markdown 확장 문법을 지원하고 있습니다.

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hackers.pub

단문(Note)과 긴 게시글(Article) 모두에서 Markdown을 지원할 뿐만 아니라 구문강조와 TeX 수식을 지원한다는 점에서 Hackers' Pub은 연합우주에서 가장 소프트웨어 프로그래머가 쓰기에 적합한 플랫폼이라고 자부합니다.

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to Elena Rossini ⁂'s post

@_elena Thanks! ☺️

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social

Open source projects I'm currently maintaining:

  • Fedify, an ActivityPub server framework for TypeScript
  • Hollo, an ActivityPub-enabled single-user microblogging software
  • BotKit, an ActivityPub bot framework for TypeScript
  • LogTape, a modern logging library for TypeScript
  • Upyo, a simple and modern email sending library for TypeScript
  • Optique, a type-safe combinatorial CLI parser for TypeScript
洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social

I've recently been working on Optique, a CLI parser combinator for TypeScript. Optique allows you to describe complex CLIs by combining smaller parts. You can also handle the CLI parsing results in a type-safe manner (see code below). The idea came from Haskell's optparse-applicative, but since TypeScript's API style is so different from Haskell's, I referenced Zod and similar libraries for the API design. For a more detailed introduction, please refer to the article I posted on Hackers' Pub!

const parser = or(
  object({
    type: constant("network"),
    host: option(
      "-h", "--host",
      string({ metavar: "HOST" }),
    ),
    port: option(
      "-p", "--port",
      integer({ metavar: "PORT", min: 0, max: 65535 }),
    ),
  }),
  object({
    type: constant("local"),
    file: option(
      "-s", "--socket-file",
      string({ metavar: "FILE" }),
    ),
  }),
)

type Result = InferValue<typeof parser>;

// The above type is inferred as:
type Result = {
    readonly type: "network";
    readonly host: string;
    readonly port: number;
} | {
    readonly type: "local";
    readonly file: string;
}
ALT text detailsconst parser = or( object({ type: constant("network"), host: option( "-h", "--host", string({ metavar: "HOST" }), ), port: option( "-p", "--port", integer({ metavar: "PORT", min: 0, max: 65535 }), ), }), object({ type: constant("local"), file: option( "-s", "--socket-file", string({ metavar: "FILE" }), ), }), ) type Result = InferValue<typeof parser>; // The above type is inferred as: type Result = { readonly type: "network"; readonly host: string; readonly port: number; } | { readonly type: "local"; readonly file: string; }
洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hackers.pub


최근 Optique라는 다소 실험적인 CLI 파서 라이브러리를 제작하게 되었습니다. 이 글을 쓰는 2025년 8월 21일 시점으로 아직 0.1.0도 릴리스되지 않았지만, 나름대로 재미있는 발상이라고 생각해서 이 글을 통해 소개합니다.

Optique는 크게 두 가지 다른 라이브러리로부터 영향을 받았습니다. 하나는 Haskell의 optparse-applicative라는 라이브러리인데, 이 라이브러리로부터 얻은 교훈은 CLI 파서도 파서 컴비네이터가 될 수 있고, 그렇게 만들었을 때 매우 유용하다는 사실입니다. 다른 하나는 TypeScript 사용자들에게 이미 익숙한 Zod입니다. 비록 optparse-applicative에서 아이디어의 줄기를 얻긴 했지만, Haskell과 TypeScript는 너무나 다른 언어라서 API를 구성하는 방식에 큰 차이가 있습니다. 그래서 API를 구성하는 방식에 있어서는 Zod를 비롯한 여러 유효성 검사 라이브러리를 참고하게 되었습니다.

Optique는 여러 작은 파서들과 파서 컴비네이터들을 레고 부품처럼 조립하여 CLI가 어떠한 모양이어야 하는지를 표현합니다. 예를 들어 가장 작은 부품 중 하나로는 option()이 있습니다:

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

이 파서를 실행하려면 run()이라는 API를 사용하면 됩니다: (참고로 run() 함수는 암시적으로 process.argv.slice(2)를 읽습니다.)

const allow: URL = run(parser);

위 코드에서 제가 일부러 URL이라는 타입을 명시하긴 했지만, 굳이 그렇게 하지 않아도 저절로 URL 타입으로 추론됩니다. 위 파서는 -a/--allow=URL 옵션만을 받아들입니다. 다른 옵션이나 인자를 줄 경우 오류가 납니다. -a/--allow=URL 옵션이 주어지지 않아도 오류가 납니다.

만약 -a/--allow=URL 옵션을 필수가 아닌 선택으로 두려면 어떻게 해야 할까요? 그럴 때는 optional() 컴비네이터로 option() 파서를 감싸면 됩니다.

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

이 파서를 실행하면 결과로 어떤 타입이 나올까요?

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

네, URL | undefined 타입이 됩니다.

아니면, 아예 -a/--allow=URL 옵션을 여러 개 받을 수 있게 해봅시다. 아래처럼 쓸 수 있게요:

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

이렇게 옵션을 여러 번 쓸 수 있게 하려면, optional() 컴비네이터 대신 multiple() 컴비네이터를 씁니다:

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

이제 슬슬 결과 타입이 어떻게 나올지 예상이 되시죠?

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

네, readonly URL[] 타입이 됩니다.

그런데, 만약 -a/--allow=URL 옵션과는 함께 쓸 수 없는 상호배타적인 -d/--disallow=URL이라는 옵션을 추가하려면 어떻게 해야 할까요? 둘 중 한 쪽의 옵션만 동시에 쓸 수 있어야 합니다. 이럴 때는 or() 컴비네이터를 사용하면 됩니다:

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

이 파서는 다음과 같은 명령들은 잘 받아들입니다:

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

하지만 다음과 같이 -a/--allow=URL 옵션과 -d/--disallow=URL 옵션이 섞여있을 때는 오류를 냅니다:

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

아무튼, 그럼 이 파서의 결과는 어떤 타입이 될까요?

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

이런, or() 컴비네이터가 감싸는 2개의 파서 모두 readonly URL[] 타입의 값을 만들기 때문에 readonly URL[] | readonly URL[] 타입이 되어, 결과적으로 readonly URL[] 타입이 되어버렸습니다. 제대로 된 변별 공용체(discriminated union) 형식으로 바꾸고 싶군요. 아래와 같은 타입이면 좋을 것 같습니다.

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

이렇게 객체 형태의 구조를 만들고 싶을 때는 object() 컴비네이터를 쓰면 됩니다:

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

변별자(discriminator)를 부여하기 위해 constant() 파서도 사용했습니다. 이 파서는 조금 특이한 파서인데, 아무 것도 읽지 않고 주어진 값을 만들기만 합니다. 즉, 항상 성공하는 파서입니다. 이렇게 변별 공용체를 구성할 때 주로 쓰이지만, 다른 창의적인 방식으로도 쓰일 수 있을 겁니다.

이제 이 파서는 우리가 원하는 타입의 결과 값을 만듭니다:

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

꼭 상호배타적인 옵션들에만 or() 컴비네이터나 object() 컴비네이터를 쓰는 건 아닙니다. 서브커맨드도 같은 원리로 구현할 수 있습니다. 하나의 커맨드에 매치되는 command() 파서와 순서 인자에 매치되는 argument() 파서를 소개합니다:

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

위 파서는 아래와 같은 명령에 매치됩니다:

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

파서의 결과 타입은 다음과 같습니다:

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

여기에 upload 서브커맨드를 추가하려면 어떻게 해야 할까요? 맞습니다, or() 컴비네이터로 엮으면 됩니다:

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 },
      ),
    })
  ),
);

위 파서는 이제 다음과 같은 명령들을 받아들일 수 있게 되었습니다:

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

이 파서의 결과 타입은 다음과 같습니다:

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); 

같은 방식을 응용하면 겹쳐진 서브커맨드(nested subcommands)도 구현할 수 있겠죠?

자, 이렇게 Optique가 CLI를 표현하는 방식을 보여드렸는데요. 어떤 것 같나요? Optique의 방식이 복잡한 CLI를 표현하기에 적합하다는 게 와닿으시나요?

물론, Optique의 방식도 완벽하지는 않습니다. 아주 전형적이고 단순한 CLI를 정의하는 데에는 오히려 더 손이 가는 것도 사실입니다. 또한, Optique는 오로지 CLI 파서의 역할만 하고 있기 때문에 일반적인 CLI 앱 프레임워크가 제공하는 다양한 기능은 제공하지 않기도 합니다. (추후 Optique에 더 많은 기능을 추가할 예정이긴 합니다만…)

그럼에도 Optique의 접근 방식에 흥미를 느끼셨다면, 소개 문서튜토리얼도 한 번 살펴보시기 바랍니다.

AmaseCocoa's avatar
AmaseCocoa

@cocoa@hackers.pub

僕がActivityPubを始めた理由 - Yaruki NotFound

https://amase.cc/posts/1755806437530-僕がactivitypubを始めた理由

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hackers.pub

Anthony Fu의 〈야크 셰이빙에 관해〉. 요즘 내 심정을 잘 대변하는 글 같다.

洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hollo.social · Reply to 洪 民憙 (Hong Minhee)'s post

最近、OptiqueというTypeScript向けのCLIパーサー「コンビネーター」を作っています。Optiqueは、複雑なCLIを小さなパーツの組み合わせで記述できる様にしてくれます。そして、そのCLIのパース結果を型安全に扱う事が出来ます。(下記のコード参照)アイデアはHaskellのoptparse-applicative から得ましたが、TypeScriptはHaskellとAPIのスタイルがかなり異なる為、APIの面ではZod等を参考にしました。詳しい紹介はHackers' Pubに投稿した記事をご覧ください!

const parser = or(
  object({
    type: constant("network"),
    host: option(
      "-h", "--host",
      string({ metavar: "HOST" }),
    ),
    port: option(
      "-p", "--port",
      integer({ metavar: "PORT", min: 0, max: 65535 }),
    ),
  }),
  object({
    type: constant("local"),
    file: option(
      "-s", "--socket-file",
      string({ metavar: "FILE" }),
    ),
  }),
)

type Result = InferValue<typeof parser>;

// Resultの推論された型
type Result = {
    readonly type: "network";
    readonly host: string;
    readonly port: number;
} | {
    readonly type: "local";
    readonly file: string;
}
ALT text detailsconst parser = or( object({ type: constant("network"), host: option( "-h", "--host", string({ metavar: "HOST" }), ), port: option( "-p", "--port", integer({ metavar: "PORT", min: 0, max: 65535 }), ), }), object({ type: constant("local"), file: option( "-s", "--socket-file", string({ metavar: "FILE" }), ), }), ) type Result = InferValue<typeof parser>; // Resultの推論された型 type Result = { readonly type: "network"; readonly host: string; readonly port: number; } | { readonly type: "local"; readonly file: string; }
洪 民憙 (Hong Minhee)'s avatar
洪 民憙 (Hong Minhee)

@hongminhee@hackers.pub


최근 Optique라는 다소 실험적인 CLI 파서 라이브러리를 제작하게 되었습니다. 이 글을 쓰는 2025년 8월 21일 시점으로 아직 0.1.0도 릴리스되지 않았지만, 나름대로 재미있는 발상이라고 생각해서 이 글을 통해 소개합니다.

Optique는 크게 두 가지 다른 라이브러리로부터 영향을 받았습니다. 하나는 Haskell의 optparse-applicative라는 라이브러리인데, 이 라이브러리로부터 얻은 교훈은 CLI 파서도 파서 컴비네이터가 될 수 있고, 그렇게 만들었을 때 매우 유용하다는 사실입니다. 다른 하나는 TypeScript 사용자들에게 이미 익숙한 Zod입니다. 비록 optparse-applicative에서 아이디어의 줄기를 얻긴 했지만, Haskell과 TypeScript는 너무나 다른 언어라서 API를 구성하는 방식에 큰 차이가 있습니다. 그래서 API를 구성하는 방식에 있어서는 Zod를 비롯한 여러 유효성 검사 라이브러리를 참고하게 되었습니다.

Optique는 여러 작은 파서들과 파서 컴비네이터들을 레고 부품처럼 조립하여 CLI가 어떠한 모양이어야 하는지를 표현합니다. 예를 들어 가장 작은 부품 중 하나로는 option()이 있습니다:

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

이 파서를 실행하려면 run()이라는 API를 사용하면 됩니다: (참고로 run() 함수는 암시적으로 process.argv.slice(2)를 읽습니다.)

const allow: URL = run(parser);

위 코드에서 제가 일부러 URL이라는 타입을 명시하긴 했지만, 굳이 그렇게 하지 않아도 저절로 URL 타입으로 추론됩니다. 위 파서는 -a/--allow=URL 옵션만을 받아들입니다. 다른 옵션이나 인자를 줄 경우 오류가 납니다. -a/--allow=URL 옵션이 주어지지 않아도 오류가 납니다.

만약 -a/--allow=URL 옵션을 필수가 아닌 선택으로 두려면 어떻게 해야 할까요? 그럴 때는 optional() 컴비네이터로 option() 파서를 감싸면 됩니다.

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

이 파서를 실행하면 결과로 어떤 타입이 나올까요?

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

네, URL | undefined 타입이 됩니다.

아니면, 아예 -a/--allow=URL 옵션을 여러 개 받을 수 있게 해봅시다. 아래처럼 쓸 수 있게요:

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

이렇게 옵션을 여러 번 쓸 수 있게 하려면, optional() 컴비네이터 대신 multiple() 컴비네이터를 씁니다:

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

이제 슬슬 결과 타입이 어떻게 나올지 예상이 되시죠?

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

네, readonly URL[] 타입이 됩니다.

그런데, 만약 -a/--allow=URL 옵션과는 함께 쓸 수 없는 상호배타적인 -d/--disallow=URL이라는 옵션을 추가하려면 어떻게 해야 할까요? 둘 중 한 쪽의 옵션만 동시에 쓸 수 있어야 합니다. 이럴 때는 or() 컴비네이터를 사용하면 됩니다:

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

이 파서는 다음과 같은 명령들은 잘 받아들입니다:

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

하지만 다음과 같이 -a/--allow=URL 옵션과 -d/--disallow=URL 옵션이 섞여있을 때는 오류를 냅니다:

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

아무튼, 그럼 이 파서의 결과는 어떤 타입이 될까요?

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

이런, or() 컴비네이터가 감싸는 2개의 파서 모두 readonly URL[] 타입의 값을 만들기 때문에 readonly URL[] | readonly URL[] 타입이 되어, 결과적으로 readonly URL[] 타입이 되어버렸습니다. 제대로 된 변별 공용체(discriminated union) 형식으로 바꾸고 싶군요. 아래와 같은 타입이면 좋을 것 같습니다.

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

이렇게 객체 형태의 구조를 만들고 싶을 때는 object() 컴비네이터를 쓰면 됩니다:

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

변별자(discriminator)를 부여하기 위해 constant() 파서도 사용했습니다. 이 파서는 조금 특이한 파서인데, 아무 것도 읽지 않고 주어진 값을 만들기만 합니다. 즉, 항상 성공하는 파서입니다. 이렇게 변별 공용체를 구성할 때 주로 쓰이지만, 다른 창의적인 방식으로도 쓰일 수 있을 겁니다.

이제 이 파서는 우리가 원하는 타입의 결과 값을 만듭니다:

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

꼭 상호배타적인 옵션들에만 or() 컴비네이터나 object() 컴비네이터를 쓰는 건 아닙니다. 서브커맨드도 같은 원리로 구현할 수 있습니다. 하나의 커맨드에 매치되는 command() 파서와 순서 인자에 매치되는 argument() 파서를 소개합니다:

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

위 파서는 아래와 같은 명령에 매치됩니다:

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

파서의 결과 타입은 다음과 같습니다:

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

여기에 upload 서브커맨드를 추가하려면 어떻게 해야 할까요? 맞습니다, or() 컴비네이터로 엮으면 됩니다:

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 },
      ),
    })
  ),
);

위 파서는 이제 다음과 같은 명령들을 받아들일 수 있게 되었습니다:

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

이 파서의 결과 타입은 다음과 같습니다:

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); 

같은 방식을 응용하면 겹쳐진 서브커맨드(nested subcommands)도 구현할 수 있겠죠?

자, 이렇게 Optique가 CLI를 표현하는 방식을 보여드렸는데요. 어떤 것 같나요? Optique의 방식이 복잡한 CLI를 표현하기에 적합하다는 게 와닿으시나요?

물론, Optique의 방식도 완벽하지는 않습니다. 아주 전형적이고 단순한 CLI를 정의하는 데에는 오히려 더 손이 가는 것도 사실입니다. 또한, Optique는 오로지 CLI 파서의 역할만 하고 있기 때문에 일반적인 CLI 앱 프레임워크가 제공하는 다양한 기능은 제공하지 않기도 합니다. (추후 Optique에 더 많은 기능을 추가할 예정이긴 합니다만…)

그럼에도 Optique의 접근 방식에 흥미를 느끼셨다면, 소개 문서튜토리얼도 한 번 살펴보시기 바랍니다.

← Newer
Older →