⁂ Article
Stop writing CLI validation. Parse it right the first time.
I have this bad habit. When something annoys me enough times, I end up building a library for it. This time, it was CLI validation code.
See, I spend a lot of time reading other people's code. Open source projects, work stuff, random GitHub repos I stumble upon at 2 AM. And I kept noticing this thing: every CLI tool has the same ugly validation code tucked away somewhere. You know the kind:
if (!opts.server && opts.port) { throw new Error("--port requires --server flag");}if (opts.server && !opts.port) { opts.port = 3000; // default port}// wait, what if they pass --port without a value?// what if the port is out of range?// what if...It's not even that this code is hard to write. It's that it's everywhere. Every project. Every CLI tool. The same patterns, slightly different flavors. Options that depend on other options. Flags that can't be used together. Arguments that only make sense in certain modes.
And here's what really got me: we solved this problem years ago for other types of data. Just… not for CLIs.
The problem with validation
There's this blog post that completely changed how I think about parsing. It's called Parse, don't validate by Alexis King. The gist? Don't parse data into a loose type and then check if it's valid. Parse it directly into a type that can only be valid.
Think about it. When you get JSON from an API, you don't just parse it as any
and then write a bunch of if-statements. You use something like Zod to parse
it directly into the shape you want. Invalid data? The parser rejects it. Done.
But with CLIs? We parse arguments into some bag of properties and then spend the next 100 lines checking if that bag makes sense. It's backwards.
So yeah, I built Optique. Not because the world desperately needed another CLI parser (it didn't), but because I was tired of seeing—and writing—the same validation code everywhere.
Three patterns I was sick of validating
Dependent options
This one's everywhere. You have an option that only makes sense when another option is enabled.
The old way? Parse everything, then check:
const opts = parseArgs(process.argv);if (!opts.server && opts.port) { throw new Error("--port requires --server");}if (opts.server && !opts.port) { opts.port = 3000;}// More validation probably lurking elsewhere...With Optique, you just describe what you want:
const config = withDefault( object({ server: flag("--server"), port: option("--port", integer()), workers: option("--workers", integer()) }), { server: false });Here's what TypeScript infers for config's type:
type Config = | { readonly server: false } | { readonly server: true; readonly port: number; readonly workers: number }The type system now understands that when server is false, port literally
doesn't exist. Not undefined, not null—it's not there. Try to access it and
TypeScript yells at you. No runtime validation needed.
Mutually exclusive options
Another classic. Pick one output format: JSON, YAML, or XML. But definitely not two.
I used to write this mess:
if ((opts.json ? 1 : 0) + (opts.yaml ? 1 : 0) + (opts.xml ? 1 : 0) > 1) { throw new Error('Choose only one output format');}(Don't judge me, you've written something similar.)
Now?
const format = or( map(option("--json"), () => "json" as const), map(option("--yaml"), () => "yaml" as const), map(option("--xml"), () => "xml" as const));The or() combinator means exactly one succeeds. The result is just
"json" | "yaml" | "xml". A single string. Not three booleans to juggle.
Environment-specific requirements
Production needs auth. Development needs debug flags. Docker needs different options than local. You know the drill.
Instead of a validation maze, you just describe each environment:
const envConfig = or( object({ env: constant("prod"), auth: option("--auth", string()), // Required in prod ssl: option("--ssl"), monitoring: option("--monitoring", url()) }), object({ env: constant("dev"), debug: optional(option("--debug")), // Optional in dev verbose: option("--verbose") }));No auth in production? Parser fails immediately. Trying to access --auth in
dev mode? TypeScript won't let you—the field doesn't exist on that type.
“But parser combinators though…”
I know, I know. “Parser combinators” sounds like something you'd need a CS degree to understand.
Here's the thing: I don't have a CS degree. Actually, I don't have any degree. But I've been using parser combinators for years because they're actually… not that hard? It's just that the name makes them sound way scarier than they are.
I'd been using them for other stuff—parsing config files, DSLs, whatever. But somehow it never clicked that you could use them for CLI parsing until I saw Haskell's optparse-applicative. That was a real “wait, of course” moment. Like, why are we doing this any other way?
Turns out it's stupidly simple. A parser is just a function. Combinators are just functions that take parsers and return new parsers. That's it.
// This is a parserconst port = option("--port", integer());// This is also a parser (made from smaller parsers)const server = object({ port: port, host: option("--host", string())});// Still a parser (parsers all the way down)const config = or(server, client);No monads. No category theory. Just functions. Boring, beautiful functions.
TypeScript does the heavy lifting
Here's the thing that still feels like cheating: I don't write types for my CLI configs anymore. TypeScript just… figures it out.
const cli = or( command("deploy", object({ action: constant("deploy"), environment: argument(string()), replicas: option("--replicas", integer()) })), command("rollback", object({ action: constant("rollback"), version: argument(string()), force: option("--force") })));// TypeScript infers this type automatically:type Cli = | { readonly action: "deploy" readonly environment: string readonly replicas: number } | { readonly action: "rollback" readonly version: string readonly force: boolean }TypeScript knows that if action is "deploy", then environment exists but
version doesn't. It knows replicas is a number. It knows force is
a boolean. I didn't tell it any of this.
This isn't just about nice autocomplete (though yeah, the autocomplete is great). It's about catching bugs before they happen. Forget to handle a new option somewhere? Code won't compile.
What actually changed for me
I've been dogfooding this for a few weeks. Some real talk:
I delete code now. Not refactor. Delete. That validation logic that used to be 30% of my CLI code? Gone. It feels weird every time.
Refactoring isn't scary. Want to know something that usually terrifies me?
Changing how a CLI takes its arguments. Like going from --input file.txt to
just file.txt as a positional argument. With traditional parsers,
you're hunting down validation logic everywhere. With this?
You change the parser definition, TypeScript immediately shows you every place
that breaks, you fix them, done. What used to be an hour of “did I catch
everything?” is now “fix the red squiggles and move on.”
My CLIs got fancier. When adding complex option relationships doesn't mean writing complex validation, you just… add them. Mutually exclusive groups? Sure. Context-dependent options? Why not. The parser handles it.
The reusability is real too:
const networkOptions = object({ host: option("--host", string()), port: option("--port", integer())});// Reuse everywhere, compose differentlyconst devServer = merge(networkOptions, debugOptions);const prodServer = merge(networkOptions, authOptions);const testServer = merge(networkOptions, mockOptions);But honestly? The biggest change is trust. If it compiles, the CLI logic works. Not “probably works” or “works unless someone passes weird arguments.” It just works.
Should you care?
If you're writing a 10-line script that takes one argument, you don't need this.
process.argv[2] and call it a day.
But if you've ever:
- Had validation logic get out of sync with your actual options
- Discovered in production that certain option combinations explode
- Spent an afternoon tracking down why
--verbosebreaks when used with--json - Written the same “option A requires option B” check for the fifth time
Then yeah, maybe you're tired of this stuff too.
Fair warning: Optique is young. I'm still figuring things out, the API might shift a bit. But the core idea—parse, don't validate—that's solid. And I haven't written validation code in months.
Still feels weird. Good weird.
Try it or don't
If this resonates:
- Tutorial: Build something real, see if you hate it
- Concepts: Primitives, constructs, modifiers, value parsers, the whole thing
- GitHub: The code, issues, angry rants
I'm not saying Optique is the answer to all CLI problems. I'm just saying I was tired of writing the same validation code everywhere, so I built something that makes it unnecessary.
Take it or leave it. But that validation code you're about to write? You probably don't need it.
JA:私には悪い癖があります。何かに十分イライラすると、それに対するライブラリを作ってしまうのです。今回は、CLI バリデーションコードがその対象でした。
私は他の人のコードを読むことに多くの時間を費やしています。オープンソースプロジェクト、仕事関連のもの、深夜2時に偶然見つけた GitHub リポジトリなど。そして、あるパターンに気づき続けていました：すべての CLI ツールには、どこかに同じような醜いバリデーションコードが隠れているのです。こんな感じのものです：
if (!opts.server && opts.port) { throw new Error("--port requires --server flag");}if (opts.server && !opts.port) { opts.port = 3000; // デフォルトポート}// ちょっと待って、--port に値を渡さない場合は？// ポートが範囲外だったら？// もし...このコードを書くのが難しいわけではありません。問題は、これがどこにでもあることです。すべてのプロジェクト。すべての CLI ツール。同じパターンで、少しずつ異なる味付け。他のオプションに依存するオプション。一緒に使えないフラグ。特定のモードでしか意味をなさない引数。
そして本当に気になったのは：私たちは他のタイプのデータに対してこの問題を何年も前に解決していたということです。ただ...CLI に対しては解決していなかったのです。
バリデーションの問題点
私のパース（構文解析）に対する考え方を完全に変えたブログ記事があります。 Alexis King によるバリデーションではなくパースをです。要点は？データを緩い型にパースしてから有効かどうかをチェックするのではなく、有効な状態しか取り得ない型に直接パースするということです。
考えてみてください。API から JSON を取得するとき、単に any としてパースしてから一連の if 文を書くわけではありません。Zod のようなものを使って、欲しい形に直接パースします。無効なデータ？パーサーがそれを拒否します。終わり。
しかし CLI では？引数をプロパティの集まりにパースして、その後100行かけてそのバッグが意味をなすかどうかをチェックします。これは逆転しています。
そういうわけで、私は Optique を作りました。世界が別の CLI パーサーを切実に必要としていたからではなく（そうではありません）、同じバリデーションコードをあらゆる場所で見る—そして書く—ことにうんざりしていたからです。
バリデーションに飽き飽きしていた3つのパターン
依存オプション
これはどこにでもあります。別のオプションが有効な場合にのみ意味を持つオプションがあります。
従来の方法？すべてをパースしてからチェックします：
const opts = parseArgs(process.argv);if (!opts.server && opts.port) { throw new Error("--port requires --server");}if (opts.server && !opts.port) { opts.port = 3000;}// おそらく他の場所にもバリデーションが潜んでいる...Optique では、欲しいものを記述するだけです：
const config = withDefault( object({ server: flag("--server"), port: option("--port", integer()), workers: option("--workers", integer()) }), { server: false });TypeScript が config の型に対して推論するものは次のとおりです：
type Config = | { readonly server: false } | { readonly server: true; readonly port: number; readonly workers: number }型システムは、server が false の場合、port が文字通り存在しないことを理解しています。undefined でも null でもなく、そこにないのです。アクセスしようとすると TypeScript が警告します。ランタイムでのバリデーションは必要ありません。
相互排他的なオプション
もう一つの典型例。出力フォーマットを一つ選びます：JSON、YAML、または XML。ただし、2つは絶対に選べません。
以前は次のようなコードを書いていました：
if ((opts.json ? 1 : 0) + (opts.yaml ? 1 : 0) + (opts.xml ? 1 : 0) > 1) { throw new Error('Choose only one output format');}（批判しないでください、あなたも似たようなものを書いたことがあるはずです。）
今では？
const format = or( map(option("--json"), () => "json" as const), map(option("--yaml"), () => "yaml" as const), map(option("--xml"), () => "xml" as const));or() コンビネータは、正確に1つだけが成功することを意味します。結果は単に "json" | "yaml" | "xml" です。3つのブール値をやりくりするのではなく、単一の文字列です。
環境固有の要件
本番環境には認証が必要です。開発環境にはデバッグフラグが必要です。Docker はローカルとは異なるオプションが必要です。おなじみのパターンですね。
バリデーションの迷路の代わりに、各環境を記述するだけです：
const envConfig = or( object({ env: constant("prod"), auth: option("--auth", string()), // 本番環境では必須 ssl: option("--ssl"), monitoring: option("--monitoring", url()) }), object({ env: constant("dev"), debug: optional(option("--debug")), // 開発環境ではオプション verbose: option("--verbose") }));本番環境で認証がない？パーサーはすぐに失敗します。開発モードで --auth にアクセスしようとしている？TypeScript はそれを許可しません—その型にはそのフィールドが存在しないからです。
「でもパーサーコンビネータって...」
わかっています。「パーサーコンビネータ」というと、理解するためにコンピュータサイエンスの学位が必要なもののように聞こえます。
実は、私はコンピュータサイエンスの学位を持っていません。実際、私はどんな学位も持っていません。しかし、パーサーコンビネータは実際には...そんなに難しくないので、何年も使ってきました。名前が実際よりもずっと怖く聞こえるだけなのです。
私は他のもの—設定ファイルのパース、DSL、その他—にパーサーコンビネータを使っていました。しかし、Haskell の optparse-applicative を見るまで、CLI パースにも使えることに気づきませんでした。それは本当に「ああ、もちろん」という瞬間でした。なぜ他の方法でやっているのか、と思いました。
実はバカみたいに単純なんです。パーサーは単なる関数です。コンビネータは、パーサーを受け取って新しいパーサーを返す関数に過ぎません。それだけです。
// これはパーサーですconst port = option("--port", integer());// これもパーサーです（より小さなパーサーから作られています）const server = object({ port: port, host: option("--host", string())});// まだパーサーです（すべてパーサーです）const config = or(server, client);モナドはありません。圏論もありません。ただの関数です。退屈で美しい関数です。
TypeScript が重労働を担当
まだズルをしているように感じるのは：もう CLI 設定の型を書かなくなったことです。TypeScript が...勝手に理解してくれます。
const cli = or( command("deploy", object({ action: constant("deploy"), environment: argument(string()), replicas: option("--replicas", integer()) })), command("rollback", object({ action: constant("rollback"), version: argument(string()), force: option("--force") })));// TypeScript は自動的にこの型を推論します：type Cli = | { readonly action: "deploy" readonly environment: string readonly replicas: number } | { readonly action: "rollback" readonly version: string readonly force: boolean }TypeScript は、action が "deploy" の場合、environment は存在するが version は存在しないことを知っています。replicas が number であることも知っています。force が boolean であることも知っています。これらは私が教えたわけではありません。
これは単に素晴らしいオートコンプリートのためだけではありません（もちろん、オートコンプリートは素晴らしいですが）。バグが発生する前に捕まえることができるのです。どこかで新しいオプションの処理を忘れた？コードはコンパイルされません。
実際に私に起きた変化
数週間、自分のプロジェクトでこれを試してきました。率直に言うと：
今はコードを削除します。 リファクタリングではなく、削除です。以前は CLI コードの 30% を占めていたバリデーションロジック？消えました。毎回奇妙な感じがします。
リファクタリングが怖くなくなりました。 通常私を恐怖に陥れるものは何か知っていますか？
CLI が引数を受け取る方法を変更することです。例えば、--input file.txt から単に file.txt という位置引数に変更するような場合です。従来のパーサーでは、あらゆる場所でバリデーションロジックを探し回ります。これでは？パーサー定義を変更すると、TypeScript はすぐに壊れるすべての場所を表示し、それらを修正すれば完了です。以前は「すべてを捕捉できたか？」という1時間の作業が、今では「赤い波線を修正して次に進む」だけです。
CLI がより洗練されました。 複雑なオプション関係を追加しても複雑なバリデーションを書く必要がなければ、単に...追加するだけです。相互排他的なグループ？もちろん。コンテキスト依存のオプション？なぜダメ？パーサーがそれを処理します。
再利用性も本物です：
const networkOptions = object({ host: option("--host", string()), port: option("--port", integer())});// どこでも再利用し、異なる方法で構成const devServer = merge(networkOptions, debugOptions);const prodServer = merge(networkOptions, authOptions);const testServer = merge(networkOptions, mockOptions);しかし正直なところ？最大の変化は信頼です。コンパイルが通れば、CLI ロジックは機能します。「おそらく機能する」や「変な引数を渡さない限り機能する」ではなく。単に機能するのです。
気にするべきか？
10行のスクリプトを書いていて、1つの引数しか取らないなら、これは必要ありません。
process.argv[2] を使って終わりにしましょう。
しかし、もしあなたが：
- バリデーションロジックが実際のオプションと同期しなくなったことがある
- 特定のオプションの組み合わせが爆発することを本番環境で発見した
--jsonと一緒に使うと--verboseが壊れる理由を追跡するのに午後を費やした- 「オプション A にはオプション B が必要」というチェックを5回目に書いた
なら、あなたもこれにうんざりしているかもしれません。
公平な警告：Optique はまだ若いです。まだ物事を整理している段階で、API は少し変わるかもしれません。しかし、核となるアイデア—バリデーションではなくパース—それは確固たるものです。そして、私は数ヶ月間バリデーションコードを書いていません。
まだ奇妙な感じがします。良い意味で奇妙です。
試すも試さないも自由
これが共感を呼ぶなら：
私は Optique がすべての CLI 問題の答えだとは言っていません。ただ、どこでも同じバリデーションコードを書くことにうんざりしていたので、それを不要にするものを作ったというだけです。
使うも使わないも自由です。しかし、これから書こうとしているバリデーションコード？おそらくそれは必要ないでしょう。
KO-KR:저는 이런 나쁜 습관이 있습니다. 어떤 것이 충분히 짜증나게 하면, 결국 그것을 위한 라이브러리를 만들게 됩니다. 이번에는 CLI 유효성 검사 코드가 그 대상이었습니다.
저는 다른 사람들의 코드를 읽는 데 많은 시간을 보냅니다. 오픈 소스 프로젝트, 업무 관련 코드, 새벽 2시에 우연히 발견한 GitHub 저장소 등을 살펴봅니다. 그리고 계속해서 이런 것을 발견했습니다: 모든 CLI 도구는 어딘가에 똑같은 못생긴 유효성 검사 코드를 숨겨두고 있습니다. 이런 종류의 코드 말이죠:
if (!opts.server && opts.port) { throw new Error("--port requires --server flag");}if (opts.server && !opts.port) { opts.port = 3000; // default port}// 잠깐, --port를 값 없이 전달하면 어떻게 될까요?// 포트가 범위를 벗어나면 어떻게 될까요?// 만약...이런 코드를 작성하기 어렵다는 게 문제가 아닙니다. 문제는 이런 코드가 어디에나 있다는 것입니다. 모든 프로젝트. 모든 CLI 도구. 같은 패턴, 약간 다른 형태로요. 다른 옵션에 의존하는 옵션들. 함께 사용할 수 없는 플래그들. 특정 모드에서만 의미가 있는 인수들.
그리고 제가 정말 깨달은 것은 이것입니다: 우리는 다른 유형의 데이터에 대해서는 이 문제를 수년 전에 해결했습니다. 단지... CLI에 대해서는 아직 해결하지 않았을 뿐입니다.
유효성 검사의 문제점
제가 파싱에 대한 생각을 완전히 바꾸게 한 블로그 포스트가 있습니다. Alexis King의 유효성 검사하지 말고, 파싱하라(Parse, don't validate)라는 글입니다. 요점은? 데이터를 느슨한 타입으로 파싱한 다음 유효한지 확인하지 말고, 유효할 수밖에 없는 타입으로 직접 파싱하라는 것입니다.
생각해 보세요. API에서 JSON을 받을 때, 그냥 any로 파싱한 다음 여러 if 문을 작성하지 않습니다. Zod와 같은 것을 사용하여 원하는 형태로 직접 파싱합니다. 유효하지 않은 데이터? 파서가 거부합니다. 끝.
하지만 CLI에서는? 인수를 속성들의 묶음으로 파싱한 다음, 그 묶음이 의미가 있는지 확인하는 데 다음 100줄을 소비합니다. 이건 거꾸로 된 방식입니다.
그래서 네, 저는 Optique를 만들었습니다. 세상이 절실히 또 다른 CLI 파서를 필요로 해서가 아니라(그렇지 않았습니다), 어디서나 같은 유효성 검사 코드를 보고—그리고 작성하는 것—에 지쳤기 때문입니다.
유효성 검사에 지친 세 가지 패턴
종속적 옵션
이것은 어디에나 있습니다. 다른 옵션이 활성화되었을 때만 의미가 있는 옵션이 있습니다.
기존 방식? 모든 것을 파싱한 다음 확인합니다:
const opts = parseArgs(process.argv);if (!opts.server && opts.port) { throw new Error("--port requires --server");}if (opts.server && !opts.port) { opts.port = 3000;}// 더 많은 유효성 검사가 다른 곳에 숨어 있을 가능성이 높습니다...Optique를 사용하면 원하는 것을 그냥 설명하면 됩니다:
const config = withDefault( object({ server: flag("--server"), port: option("--port", integer()), workers: option("--workers", integer()) }), { server: false });TypeScript가 config의 타입을 다음과 같이 추론합니다:
type Config = | { readonly server: false } | { readonly server: true; readonly port: number; readonly workers: number }이제 타입 시스템은 server가 false일 때 port가 문자 그대로 존재하지 않는다는 것을 이해합니다. undefined도 아니고, null도 아니며—그냥 없습니다. 접근하려고 하면 TypeScript가 경고합니다. 런타임 유효성 검사가 필요 없습니다.
상호 배타적 옵션
또 다른 클래식입니다. 하나의 출력 형식을 선택하세요: JSON, YAML 또는 XML. 하지만 절대 두 개를 동시에 선택하면 안 됩니다.
예전에는 이런 지저분한 코드를 작성했습니다:
if ((opts.json ? 1 : 0) + (opts.yaml ? 1 : 0) + (opts.xml ? 1 : 0) > 1) { throw new Error('Choose only one output format');}(판단하지 마세요, 여러분도 비슷한 것을 작성해 보셨을 겁니다.)
이제는?
const format = or( map(option("--json"), () => "json" as const), map(option("--yaml"), () => "yaml" as const), map(option("--xml"), () => "xml" as const));or() 결합자는 정확히 하나만 성공한다는 의미입니다. 결과는 단순히 "json" | "yaml" | "xml"입니다. 하나의 문자열입니다. 세 개의 불리언을 다룰 필요가 없습니다.
환경별 요구사항
프로덕션에는 인증이 필요합니다. 개발에는 디버그 플래그가 필요합니다. Docker는 로컬과 다른 옵션이 필요합니다. 여러분도 알다시피요.
유효성 검사 미로 대신, 각 환경을 그냥 설명하면 됩니다:
const envConfig = or( object({ env: constant("prod"), auth: option("--auth", string()), // 프로덕션에서 필수 ssl: option("--ssl"), monitoring: option("--monitoring", url()) }), object({ env: constant("dev"), debug: optional(option("--debug")), // 개발 모드에서 선택 사항 verbose: option("--verbose") }));프로덕션에서 인증이 없나요? 파서가 즉시 실패합니다. 개발 모드에서 --auth에 접근하려고 하나요? TypeScript가 허용하지 않습니다—해당 필드는 그 타입에 존재하지 않습니다.
"하지만 파서 컴비네이터라니..."
알아요, 알아요. "파서 컴비네이터"는 이해하려면 컴퓨터 과학 학위가 필요한 것처럼 들립니다.
사실은 이렇습니다: 저는 컴퓨터 과학 학위가 없습니다. 사실, 저는 어떤 학위도 없습니다. 하지만 저는 수년 동안 파서 컴비네이터를 사용해 왔습니다. 왜냐하면 그것들이 실제로... 그렇게 어렵지 않기 때문입니다. 단지 이름이 실제보다 훨씬 더 무섭게 들릴 뿐입니다.
저는 다른 것들—설정 파일 파싱, DSL, 기타 등등—에 파서 컴비네이터를 사용해 왔습니다. 하지만 Haskell의 optparse-applicative를 볼 때까지 CLI 파싱에도 사용할 수 있다는 것이 와닿지 않았습니다. 그때 정말 "잠깐, 당연하잖아"라는 순간이었습니다. 왜 우리가 다른 방식으로 이것을 하고 있었을까요?
알고 보니 이것은 어처구니없이 간단합니다. 파서는 그저 함수일 뿐입니다. 컴비네이터는 파서를 받아 새로운 파서를 반환하는 함수일 뿐입니다. 그게 전부입니다.
// 이것은 파서입니다const port = option("--port", integer());// 이것도 파서입니다 (더 작은 파서들로 만들어짐)const server = object({ port: port, host: option("--host", string())});// 여전히 파서입니다 (계속해서 파서들로 구성됨)const config = or(server, client);모나드 없음. 범주론 없음. 그냥 함수들입니다. 지루하고, 아름다운 함수들.
TypeScript가 무거운 작업을 처리합니다
여기서 아직도 속임수 같은 느낌이 드는 것은: 저는 더 이상 CLI 설정에 대한 타입을 작성하지 않습니다. TypeScript가 그냥... 알아냅니다.
const cli = or( command("deploy", object({ action: constant("deploy"), environment: argument(string()), replicas: option("--replicas", integer()) })), command("rollback", object({ action: constant("rollback"), version: argument(string()), force: option("--force") })));// TypeScript는 이 타입을 자동으로 추론합니다:type Cli = | { readonly action: "deploy" readonly environment: string readonly replicas: number } | { readonly action: "rollback" readonly version: string readonly force: boolean }TypeScript는 action이 "deploy"이면 environment는 존재하지만 version은 존재하지 않는다는 것을 알고 있습니다. replicas가 number라는 것도 알고 있습니다. force가 boolean이라는 것도 알고 있습니다. 저는 이 중 어떤 것도 TypeScript에게 알려주지 않았습니다.
이것은 단지 좋은 자동 완성에 관한 것이 아닙니다(물론 자동 완성도 훌륭합니다). 이것은 버그가 발생하기 전에 잡아내는 것에 관한 것입니다. 어딘가에서 새로운 옵션을 처리하는 것을 잊으셨나요? 코드가 컴파일되지 않을 것입니다.
내게 실제로 무엇이 바뀌었는가
저는 몇 주 동안 이것을 직접 사용해 보았습니다. 솔직한 이야기를 해보겠습니다:
이제 코드를 삭제합니다. 리팩토링이 아니라 삭제입니다. 예전에 CLI 코드의 30%를 차지했던 유효성 검사 로직? 사라졌습니다. 매번 이상한 느낌이 듭니다.
리팩토링이 무섭지 않습니다. 보통 저를 겁먹게 하는 것이 무엇인지 아시나요? CLI가 인수를 받는 방식을 변경하는 것입니다. 예를 들어 --input file.txt에서 위치 인수로서의 file.txt로 변경하는 것 같은 경우요. 전통적인 파서를 사용하면 모든 곳에서 유효성 검사 로직을 찾아야 합니다. 이 방식에서는? 파서 정의를 변경하면 TypeScript가 즉시 깨지는 모든 위치를 보여주고, 그것들을 수정하면 끝입니다. 예전에는 "모든 것을 잡았을까?"라는 생각으로 한 시간이 걸렸던 것이 이제는 "빨간 물결선을 수정하고 넘어가자"가 되었습니다.
내 CLI가 더 멋져졌습니다. 복잡한 옵션 관계를 추가하는 것이 복잡한 유효성 검사를 작성하는 것을 의미하지 않을 때, 여러분은 그냥... 추가합니다. 상호 배타적 그룹? 물론이죠. 컨텍스트 의존적 옵션? 왜 안 되겠어요. 파서가 처리합니다.
재사용성도 실제로 있습니다:
const networkOptions = object({ host: option("--host", string()), port: option("--port", integer())});// 어디서나 재사용하고, 다르게 구성하세요const devServer = merge(networkOptions, debugOptions);const prodServer = merge(networkOptions, authOptions);const testServer = merge(networkOptions, mockOptions);하지만 솔직히? 가장 큰 변화는 신뢰입니다. 컴파일되면 CLI 로직이 작동합니다. "아마도 작동할 것"이나 "누군가 이상한 인수를 전달하지 않는 한 작동할 것"이 아닙니다. 그냥 작동합니다.
관심을 가져야 할까요?
만약 하나의 인수를 받는 10줄짜리 스크립트를 작성하고 있다면, 이것이 필요하지 않습니다. process.argv[2]를 사용하고 끝내세요.
하지만 다음과 같은 경험이 있다면:
- 유효성 검사 로직이 실제 옵션과 동기화되지 않은 경우
- 특정 옵션 조합이 프로덕션에서 폭발한다는 것을 발견한 경우
--json과 함께 사용할 때--verbose가 왜 깨지는지 추적하는 데 오후 시간을 보낸 경우- 다섯 번째로 "옵션 A는 옵션 B가 필요합니다" 검사를 작성한 경우
그렇다면 네, 아마도 여러분도 이런 것들에 지쳤을 것입니다.
공정한 경고: Optique는 아직 초기 단계입니다. 저는 아직 여러 가지를 알아가는 중이고, API가 약간 변경될 수 있습니다. 하지만 핵심 아이디어—유효성 검사하지 말고, 파싱하라—는 확고합니다. 그리고 저는 몇 달 동안 유효성 검사 코드를 작성하지 않았습니다.
여전히 이상한 느낌입니다. 좋은 이상함이죠.
시도하거나 말거나
이것이 공감된다면:
저는 Optique가 모든 CLI 문제의 해답이라고 말하는 것이 아닙니다. 단지 저는 어디에서나 같은 유효성 검사 코드를 작성하는 것에 지쳐서, 그것을 불필요하게 만드는 무언가를 만들었다고 말하는 것뿐입니다.
받아들이든 말든 여러분의 선택입니다. 하지만 여러분이 지금 작성하려는 그 유효성 검사 코드? 아마도 필요하지 않을 겁니다.
中文（中国）:我有个坏习惯。当某件事让我烦恼多次后，我最终会为它构建一个库。这次，问题出在 CLI 验证代码上。
我花了大量时间阅读其他人的代码。开源项目、工作相关的代码、凌晨 2 点偶然发现的 GitHub 仓库。我不断注意到这样一件事：每个 CLI 工具都在某处藏着相同的丑陋验证代码。你知道是哪种：
if (!opts.server && opts.port) { throw new Error("--port requires --server flag");}if (opts.server && !opts.port) { opts.port = 3000; // default port}// 等等，如果他们传递 --port 但没有值怎么办？// 如果端口超出范围怎么办？// 如果...这些代码并不难写。问题是它们无处不在。每个项目。每个 CLI 工具。相同的模式，略有不同的风格。依赖于其他选项的选项。不能一起使用的标志。只在特定模式下有意义的参数。
真正让我受不了的是：我们多年前就为其他类型的数据解决了这个问题。只是...没有为 CLI 解决。
验证的问题
有一篇博客文章完全改变了我对解析的看法。它是 Alexis King 写的 Parse, don't validate（解析，而非验证）。要点是什么？不要将数据解析为松散类型然后检查它是否有效。直接将其解析为只能有效的类型。
想想看。当你从 API 获取 JSON 时，你不会仅仅将其解析为 any 然后编写一堆 if 语句。你会使用像 Zod 这样的工具直接将其解析为你想要的形状。无效数据？解析器拒绝它。完成。
但对于 CLI 呢？我们将参数解析为一堆属性，然后花接下来的 100 行检查这堆东西是否有意义。这是本末倒置。
所以，我构建了 Optique。不是因为世界迫切需要另一个 CLI 解析器（它不需要），而是因为我厌倦了看到——和编写——到处都是相同的验证代码。
我厌倦了验证的三种模式
依赖选项
这种情况无处不在。你有一个选项，只有在另一个选项启用时才有意义。
旧方法？解析所有内容，然后检查：
const opts = parseArgs(process.argv);if (!opts.server && opts.port) { throw new Error("--port requires --server");}if (opts.server && !opts.port) { opts.port = 3000;}// 更多验证可能潜伏在其他地方...使用 Optique，你只需描述你想要的：
const config = withDefault( object({ server: flag("--server"), port: option("--port", integer()), workers: option("--workers", integer()) }), { server: false });以下是 TypeScript 为 config 类型推断的结果：
type Config = | { readonly server: false } | { readonly server: true; readonly port: number; readonly workers: number }类型系统现在理解当 server 为 false 时，port 字面上不存在。不是 undefined，不是 null——它根本不在那里。尝试访问它，TypeScript 会对你大喊大叫。不需要运行时验证。
互斥选项
另一个经典案例。选择一种输出格式：JSON、YAML 或 XML。但绝对不能同时选两种。
我过去会写这样的混乱代码：
if ((opts.json ? 1 : 0) + (opts.yaml ? 1 : 0) + (opts.xml ? 1 : 0) > 1) { throw new Error('Choose only one output format');}（别评判我，你也写过类似的东西。）
现在呢？
const format = or( map(option("--json"), () => "json" as const), map(option("--yaml"), () => "yaml" as const), map(option("--xml"), () => "xml" as const));or() 组合器意味着只有一个会成功。结果只是 "json" | "yaml" | "xml"。一个字符串。不是三个需要处理的布尔值。
环境特定需求
生产环境需要认证。开发环境需要调试标志。Docker 需要与本地不同的选项。你知道这种情况。
与其使用验证迷宫，不如直接描述每个环境：
const envConfig = or( object({ env: constant("prod"), auth: option("--auth", string()), // 在生产环境中必需 ssl: option("--ssl"), monitoring: option("--monitoring", url()) }), object({ env: constant("dev"), debug: optional(option("--debug")), // 在开发环境中可选 verbose: option("--verbose") }));生产环境中没有认证？解析器立即失败。尝试在开发模式下访问 --auth？TypeScript 不会让你这么做——该字段在那个类型上不存在。
"但是解析器组合器..."
我知道，我知道。"解析器组合器"听起来像是需要计算机科学学位才能理解的东西。
事实是：我没有计算机科学学位。实际上，我没有任何学位。但我已经使用解析器组合器多年了，因为它们实际上...并不那么难？只是这个名字让它们听起来比实际情况更可怕。
我一直在将它们用于其他事情——解析配置文件、DSL 等。但直到我看到 Haskell 的 optparse-applicative 之前，我从未意识到可以将它们用于 CLI 解析。那是一个真正的"等等，当然"时刻。就像，为什么我们要用其他方式来做这件事？
事实证明这非常简单。解析器只是一个函数。组合器只是接受解析器并返回新解析器的函数。就是这样。
// 这是一个解析器const port = option("--port", integer());// 这也是一个解析器（由更小的解析器组成）const server = object({ port: port, host: option("--host", string())});// 仍然是一个解析器（一直都是解析器）const config = or(server, client);没有单子。没有范畴论。只有函数。平凡而美丽的函数。
TypeScript 完成繁重工作
这里有一点仍然感觉像是作弊：我不再为我的 CLI 配置编写类型。TypeScript 只是...自己搞定了。
const cli = or( command("deploy", object({ action: constant("deploy"), environment: argument(string()), replicas: option("--replicas", integer()) })), command("rollback", object({ action: constant("rollback"), version: argument(string()), force: option("--force") })));// TypeScript 自动推断出这个类型：type Cli = | { readonly action: "deploy" readonly environment: string readonly replicas: number } | { readonly action: "rollback" readonly version: string readonly force: boolean }TypeScript 知道如果 action 是 "deploy"，那么 environment 存在但 version 不存在。它知道 replicas 是一个 number。它知道 force 是一个 boolean。我没有告诉它这些。
这不仅仅是关于良好的自动完成（尽管是的，自动完成很棒）。这是关于在问题发生前捕获它们。在某处忘记处理新选项？代码将无法编译。
对我来说实际发生了什么变化
我已经自己试用这个库几周了。一些真实感受：
我现在删除代码。 不是重构。是删除。那些曾经占我 CLI 代码 30% 的验证逻辑？消失了。每次这样做都感觉很奇怪。
重构不再可怕。 想知道什么通常让我感到恐惧吗？改变 CLI 接收参数的方式。比如从 --input file.txt 改为仅仅使用 file.txt 作为位置参数。使用传统解析器，你需要到处寻找验证逻辑。而现在呢？你更改解析器定义，TypeScript 立即显示每个出错的地方，你修复它们，完成。过去需要一小时的"我是否捕获了所有内容？"现在变成了"修复红色波浪线然后继续"。
我的 CLI 变得更高级。 当添加复杂选项关系不再意味着编写复杂验证时，你只是...添加它们。互斥组？当然可以。上下文相关选项？为什么不呢。解析器处理这一切。
可重用性也是真实的：
const networkOptions = object({ host: option("--host", string()), port: option("--port", integer())});// 到处重用，以不同方式组合const devServer = merge(networkOptions, debugOptions);const prodServer = merge(networkOptions, authOptions);const testServer = merge(networkOptions, mockOptions);但老实说？最大的变化是信任。如果它编译通过，CLI 逻辑就能工作。不是"可能工作"或"除非有人传递奇怪参数否则工作"。它就是能工作。
你应该关心吗？
如果你正在编写一个只接受一个参数的 10 行脚本，你不需要这个。使用 process.argv[2] 就完事了。
但如果你曾经：
- 让验证逻辑与你的实际选项不同步
- 在生产环境中发现某些选项组合会导致崩溃
- 花了一个下午追踪为什么
--verbose与--json一起使用时会出错 - 第五次编写相同的"选项 A 需要选项 B"检查
那么是的，也许你也厌倦了这些事情。
公平警告：Optique 还很年轻。我仍在摸索，API 可能会有一些变化。但核心理念——解析，而非验证——是坚实的。而且我已经几个月没有编写验证代码了。
仍然感觉很奇怪。好的那种奇怪。
试试看或者不试
如果这引起了你的共鸣：
我并不是说 Optique 是所有 CLI 问题的答案。我只是说我厌倦了到处编写相同的验证代码，所以我构建了一个让它变得不必要的工具。
接受它或者不接受。但是你即将编写的那些验证代码？你可能并不需要它。
中文（台湾）:我有個壞習慣。當某件事情煩擾我足夠多次後，我最終會為它建立一個函式庫。這次，問題出在 CLI 驗證程式碼上。
我花了很多時間閱讀其他人的程式碼。開源專案、工作相關的程式碼、凌晨 2 點偶然發現的 GitHub 儲存庫。我不斷注意到這個現象：每個 CLI 工具都在某處藏有相同的醜陋驗證程式碼。你知道是哪種：
if (!opts.server && opts.port) { throw new Error("--port requires --server flag");}if (opts.server && !opts.port) { opts.port = 3000; // default port}// 等等，如果他們傳入 --port 但沒有值怎麼辦？// 如果端口超出範圍怎麼辦？// 如果...這些程式碼並不難寫。問題是它們無處不在。每個專案。每個 CLI 工具。相同的模式，略微不同的風格。依賴於其他選項的選項。不能一起使用的標誌。只在特定模式下有意義的參數。
而真正讓我受不了的是：我們多年前就已經為其他類型的資料解決了這個問題。只是...沒有為 CLI 解決。
驗證的問題
有一篇部落格文章徹底改變了我對解析的看法。它是 Alexis King 寫的 Parse, don't validate。要點是什麼？不要將資料解析成寬鬆的型別然後檢查它是否有效。直接將它解析成一個只能是有效的型別。
想想看。當你從 API 獲取 JSON 時，你不會只是將它解析為 any 然後寫一堆 if 陳述式。你會使用像 Zod 這樣的工具直接將它解析成你想要的形狀。無效資料？解析器拒絕它。完成。
但對於 CLI 呢？我們將參數解析成一堆屬性，然後花接下來的 100 行檢查這堆屬性是否合理。這是本末倒置。
所以，我建立了 Optique。不是因為世界迫切需要另一個 CLI 解析器（它不需要），而是因為我厭倦了到處看到——和撰寫——相同的驗證程式碼。
三種我厭倦了驗證的模式
相依選項
這種情況無處不在。你有一個選項，只有在另一個選項啟用時才有意義。
舊方法？解析所有內容，然後檢查：
const opts = parseArgs(process.argv);if (!opts.server && opts.port) { throw new Error("--port requires --server");}if (opts.server && !opts.port) { opts.port = 3000;}// 更多驗證可能潛伏在其他地方...使用 Optique，你只需描述你想要的：
const config = withDefault( object({ server: flag("--server"), port: option("--port", integer()), workers: option("--workers", integer()) }), { server: false });以下是 TypeScript 為 config 推斷的型別：
type Config = | { readonly server: false } | { readonly server: true; readonly port: number; readonly workers: number }型別系統現在理解當 server 為 false 時，port 字面上不存在。不是 undefined，不是 null——它根本不在那裡。嘗試存取它，TypeScript 就會對你大吼大叫。不需要執行時驗證。
互斥選項
另一個經典案例。選擇一種輸出格式：JSON、YAML 或 XML。但絕對不能同時選兩種。
我過去常寫這種混亂的程式碼：
if ((opts.json ? 1 : 0) + (opts.yaml ? 1 : 0) + (opts.xml ? 1 : 0) > 1) { throw new Error('Choose only one output format');}（別評判我，你也寫過類似的東西。）
現在呢？
const format = or( map(option("--json"), () => "json" as const), map(option("--yaml"), () => "yaml" as const), map(option("--xml"), () => "xml" as const));or() 組合器意味著只有一個會成功。結果只是 "json" | "yaml" | "xml"。一個字串。不是三個要處理的布林值。
環境特定需求
生產環境需要認證。開發環境需要除錯標誌。Docker 需要與本地不同的選項。你知道這種情況。
與其建立一個驗證迷宮，你只需描述每個環境：
const envConfig = or( object({ env: constant("prod"), auth: option("--auth", string()), // 在生產環境中必需 ssl: option("--ssl"), monitoring: option("--monitoring", url()) }), object({ env: constant("dev"), debug: optional(option("--debug")), // 在開發環境中可選 verbose: option("--verbose") }));生產環境中沒有認證？解析器立即失敗。嘗試在開發模式下存取 --auth？TypeScript 不會讓你這麼做——該欄位在那個型別上不存在。
"但是解析器組合器..."
我知道，我知道。"解析器組合器"聽起來像是需要計算機科學學位才能理解的東西。
事實是：我沒有計算機科學學位。實際上，我沒有任何學位。但我已經使用解析器組合器多年了，因為它們實際上...並不那麼難？只是這個名稱讓它們聽起來比實際情況更可怕。
我一直在將它們用於其他事情——解析配置文件、領域特定語言等等。但直到我看到 Haskell 的 optparse-applicative 之前，我從未想到可以將它們用於 CLI 解析。那是一個真正的"等等，當然"時刻。就像，為什麼我們要用其他方式來做這件事？
事實證明這非常簡單。解析器只是一個函數。組合器只是接受解析器並返回新解析器的函數。就是這樣。
// 這是一個解析器const port = option("--port", integer());// 這也是一個解析器（由更小的解析器組成）const server = object({ port: port, host: option("--host", string())});// 仍然是一個解析器（一路都是解析器）const config = or(server, client);沒有單子。沒有範疇論。只有函數。平凡但美麗的函數。
TypeScript 完成繁重工作
這裡有一點仍然感覺像是作弊：我不再為我的 CLI 配置寫型別。TypeScript 就...自己搞定了。
const cli = or( command("deploy", object({ action: constant("deploy"), environment: argument(string()), replicas: option("--replicas", integer()) })), command("rollback", object({ action: constant("rollback"), version: argument(string()), force: option("--force") })));// TypeScript 自動推斷出這個型別：type Cli = | { readonly action: "deploy" readonly environment: string readonly replicas: number } | { readonly action: "rollback" readonly version: string readonly force: boolean }TypeScript 知道如果 action 是 "deploy"，那麼 environment 存在但 version 不存在。它知道 replicas 是一個 number。它知道 force 是一個 boolean。我沒有告訴它這些。
這不僅僅是關於良好的自動完成（雖然是的，自動完成很棒）。這是關於在問題發生前捕捉錯誤。在某處忘記處理新選項？程式碼將無法編譯。
對我來說實際改變了什麼
我已經自己使用這個工具幾週了。一些真實感受：
我現在刪除程式碼。 不是重構。是刪除。那些曾經佔我 CLI 程式碼 30% 的驗證邏輯？消失了。每次這樣做都感覺很奇怪。
重構不再可怕。 想知道什麼事通常讓我感到恐懼？改變 CLI 接收參數的方式。比如從 --input file.txt 改為僅僅是 file.txt 作為位置參數。使用傳統解析器，你需要到處尋找驗證邏輯。而現在呢？你改變解析器定義，TypeScript 立即顯示每個出錯的地方，你修復它們，完成。過去需要一小時的"我是否捕捉到所有問題？"現在變成了"修復紅色波浪線然後繼續前進。"
我的 CLI 變得更精緻。 當添加複雜的選項關係不再意味著編寫複雜的驗證時，你就...添加它們。互斥群組？當然可以。上下文相關選項？為什麼不呢。解析器處理這一切。
可重用性也是真實的：
const networkOptions = object({ host: option("--host", string()), port: option("--port", integer())});// 到處重用，以不同方式組合const devServer = merge(networkOptions, debugOptions);const prodServer = merge(networkOptions, authOptions);const testServer = merge(networkOptions, mockOptions);但老實說？最大的變化是信任。如果它編譯通過，CLI 邏輯就能正常工作。不是"可能有效"或"除非有人傳入奇怪的參數才有效"。它就是有效。
你應該關心嗎？
如果你正在編寫一個只接受一個參數的 10 行腳本，你不需要這個。使用 process.argv[2] 就完事了。
但如果你曾經：
- 讓驗證邏輯與你的實際選項不同步
- 在生產環境中發現某些選項組合會爆炸
- 花了一個下午追蹤為什麼
--verbose與--json一起使用時會出錯 - 第五次編寫相同的"選項 A 需要選項 B"檢查
那麼是的，也許你也厭倦了這些事情。
公平警告：Optique 還很年輕。我仍在摸索，API 可能會有些變化。但核心理念——解析，而非驗證——是穩固的。而且我已經幾個月沒有編寫驗證程式碼了。
仍然感覺很奇怪。好的那種奇怪。
嘗試或不嘗試
如果這引起了你的共鳴：
我並不是說 Optique 是所有 CLI 問題的答案。我只是說我厭倦了到處編寫相同的驗證程式碼，所以我建立了一個讓它變得不必要的工具。
接受或拒絕都可以。但是你即將編寫的那些驗證程式碼？你可能並不需要它。
