【免费下载链接】optiqueType-safe combinatorial CLI parser for TypeScript项目地址https://gitcode.com/gh_mirrors/op/optique点击查看免费下载Optique 是一个面向 TypeScript 的类型安全组合式 CLI 解析器type-safe combinatorial CLI parser。这份速查表聚焦最常被用到的六大组合子——object()、or()、merge()、optional()、multiple()、map()用最少的代码讲清楚每个函数做什么、类型如何变化、什么时候该选它帮你在构建子命令、共享选项、重复参数等场景时快速选对组合子。 一屏速查表六大组合子怎么选组合子一句话定位结果类型所在模块object()把命名字段组成结构化对象对象字段名→值optique/core/constructsor()互斥备选按顺序逐个尝试联合类型可收窄optique/core/constructsmerge()把多个解析器合并成一个对象合并后的对象optique/core/constructsoptional()允许字段缺失T \| undefinedoptique/core/modifiersmultiple()收集重复出现为数组数组T[]optique/core/modifiersmap()变换解析出的值映射后的类型Uoptique/core/modifiers记忆口诀object 按名分组、or 选一个、merge 组合并组、optional 允许缺席、multiple 收集重复、map 变换结果。1️⃣ object()多数 CLI 结构的地基object()接收一个字段名 → 解析器的映射返回结构化对象是几乎所有 CLI 应用的基础构件。const serverConfig object({ name: argument(string({ metavar: NAME })), port: option(-p, --port, integer()), verbose: option(-v, --verbose), });关键要点无需手写类型注解InferValuetypeof serverConfig会自动推导出完整对象类型。第一个参数可传标签如object(Network, {...})帮助文本中会显示为分组标题。整体优先级取组成解析器中的最高值因此内嵌的 command 字段会优先被尝试。源码入口packages/core/src/constructs.ts。2️⃣ or()互斥模式与子命令分发or()按顺序尝试每个备选直到某一个成功是server 模式 / client 模式以及子命令结构的标准做法。const gitLike or( command(add, object({ type: constant(add), files: multiple(argument(string())), })), command(commit, object({ type: constant(commit), message: option(-m, --message, string()), })), );关键要点配合constant()字段会形成 TypeScript 判别联合discriminated union可对type字段写类型安全的switch。单次or()调用最多 15 个分支更多时拆成嵌套分组。想让一个都不选也合法并得到undefined用optional()包住整个or()。错误消息可通过errors.noMatch选项自定义会根据上下文期望的是 option / command / argument自动适配措辞。源码入口packages/core/src/constructs.ts可运行示例见 examples/patterns/subcommands.ts 与 examples/patterns/mutually-exclusive-options.ts。3️⃣ merge()模块化复用选项组merge()把多个产生对象的解析器合并为一个解析器是实现同一选项组在多个命令间复用的关键。const globalOptions object({ verbose: option(-v, --verbose), config: option(-c, --config, string()), }); const deployParser merge(globalOptions, deployOptions);关键要点最常见模式是merge(globals, or(...))把全局选项提到每个子命令分支之外避免在每条命令里重复声明。不限于object()withDefault()、map()等产生对象的解析器同样可以合并类型会智能推断。与or()一样受 15 个参数上限约束也支持标签参数在帮助文本中整组显示。可用optional()包裹某个对象组让整个分组变成可选功能组不与必填参数冲突。源码入口packages/core/src/constructs.ts实战配方见 examples/patterns/shared-options.ts。4️⃣ optional()显式允许未提供optional()让任何解析器变成可选匹配成功就返回其值失败则返回undefined不报错、不消耗输入。const backupConfig object({ source: argument(string({ metavar: SRC })), compress: optional(option(-c, --compress, choice([gzip, bzip2]))), });关键要点类型从T变为T | undefined编译器会强制你处理值可能不存在的情况避免运行时误判。当值缺失本身有语义时使用它如果你想要一个兜底值而不是undefined应改用withDefault()。它是把or()变成全部可选的标准搭配optional(or(flagA, flagB))。源码入口packages/core/src/modifiers.ts。5️⃣ multiple()重复参数收集成数组multiple()允许解析器多次匹配并把所有结果收集到数组中适合多个输入文件、include 路径、环境变量等可重复选项。const parser object({ files: multiple(argument(string()), { min: 1, max: 5 }), includes: multiple(option(-I, --include, string())), });关键要点未提供任何匹配时返回空数组而非失败因此重复选项天然可选取值前无需判空。约束选项{ min, max }控制最少与最多出现次数例如恰好 2~4 个文件。常与map()搭配把数组转成Set去重小写或 key-value 对象。源码入口packages/core/src/modifiers.ts。6️⃣ map()变换解析结果map()用映射函数变换解析结果同时保留原解析逻辑适合类型转换、格式归一化、派生字段等场景。const parser object({ upperName: map(option(-n, --name, string()), (name) name.toUpperCase()), tags: map(multiple(option(-t, --tag, string())), (tags) new Set(tags.map((tag) tag.toLowerCase()))), });关键要点变换函数必须返回新值不能原地修改输入延迟提示解析时输入可能是共享占位引用原地修改会污染后续解析。支持链式流式写法如option(--port, integer()).map((v) v 1).withDefault(3001)与独立函数写法等价。常与or()搭配把每个分支的 flag 映射成字符串标签map(flag(--verbose), () verbose as const)让联合类型更可读。源码入口packages/core/src/modifiers.ts。 典型组合套路组合子的威力在套娃场景典型组合子命令 全局选项merge(globals, or(cmdA, cmdB, ...))全部可选的互斥项optional(or(flagA, flagB))详细度等级数 flag 次数optional(map(multiple(flag(--verbose)), (v) v.length))重复参数转 Set / 对象map(multiple(option(-t, string())), ...)条件性选项组merge(withDefault(object({...}), { flag: false }), globalOptions)组合之后帮助文本、shell 补全、man 页面都由同一个解析器定义生成无需手工同步维护。组合子产生的错误信息如or()的noMatch同样是结构化 Message选项名、值、metavar 会在终端中着色高亮管道或 CI 环境下自动降级为带引号的纯文本方便脚本消费。更多细节见 docs/concepts/messages.md。 选型决策流拿不准时按这个顺序问自己想把一堆字段按名字组织成对象 →object()要几个里选一的互斥模式或子命令 →or()想把同一组选项在多处复用 →merge()某字段允许不出现 →optional()某参数可以出现多次 →multiple()想在解析后变换值 →map()如果结果类型长得不对先想少套了哪个组合子而不是重写整个解析器——这正是组合式解析器复杂行为由简单积木组合的核心思想。 参考资料构造组合子官方文档docs/concepts/constructs.md修饰组合子官方文档docs/concepts/modifiers.md核心实现源码packages/core/src/constructs.ts、packages/core/src/modifiers.ts可运行模式示例目录examples/patterns/推荐从 conditional-options.ts、dependent-options.ts、verbosity-levels.ts 入手赞分享【免费下载链接】optiqueType-safe combinatorial CLI parser for TypeScript项目地址https://gitcode.com/gh_mirrors/op/optique点击查看免费下载相关推荐如何跨 1000 多个网站查出社交账号Social-Analyzer 完整实操指南如何跨 1000 多个网站查出社交账号Social Analyzer 完整实操指南 手里只有一个用户名想知道这个人出现在哪些网站上逐个打开上千家站点去猜不后端网络安全网页爬虫Pixelle-Video终极指南AI全自动短视频创作从入门到精通Pixelle Video终极指南AI全自动短视频创作从入门到精通 Pixelle Video是一款革命性的AI全自动短视频引擎能够将你的创意想法一键转化为人工智能AI 应用媒体生成视频视频处理语音数字人MCP 服务Reactor Core 组合操作符终极指南掌握 zip、combineLatest、merge 三大核心工具Reactor Core 组合操作符终极指南掌握 zip、combineLatest、merge 三大核心工具 在反应式编程的世界中Reactor Core后端异步编程上一篇Bili2text终极指南3步完成B站视频转文字轻松获取视频字幕内容下一篇5步搞定bili2text安装错误从零到完美运行的全流程指南 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考