Optique 0.4.0: ヘルプの改善、リッチなドキュメント、そして Temporal サポート

洪 民憙 (Hong Minhee) @hongminhee@hackers.pub

Optique 0.4.0 のリリースを発表できることを嬉しく思います。このバージョンでは、ヘルプテキストの構成の大幅な改善、ドキュメント機能の強化、そして包括的な Temporal API サポートの導入が行われました。

Optique は TypeScript 向けの型安全な組み合わせ式 CLI パーサーで、コマンドラインインターフェースの構築を直感的かつ保守しやすくします。このリリースでは、CLI アプリケーションをよりユーザーフレンドリーで保守しやすくすることに焦点を当てています。

ヘルプテキスト構成の改善

Optique 0.4.0 における最も目に見える改善点の一つは、ヘルプテキスト構成の強化です。オプションをより効果的にラベル付けしてグループ化できるようになり、複雑な CLI をユーザーにとってより分かりやすくしました。

ラベル付きマージグループ

merge() コンビネータがオプションのラベルパラメータを受け入れるようになり、開発者がクリーンなコード構造と整理されたヘルプ出力の間で選択しなければならないという一般的な問題を解決しました：

// 以前：ラベルなしのマージされたオプションは散らばって表示されていた
const config = merge(connectionOptions, performanceOptions);

// 現在：関連するオプションを明確なセクションの下にグループ化
const config = merge(
  "Server Configuration",  // 新しいラベルパラメータ
  connectionOptions,
  performanceOptions
);

この単純な追加は、特に複数の再利用可能なモジュールにまたがる多くのオプションを持つ CLI において、ヘルプテキストの読みやすさに大きな違いをもたらします。

結果として得られるヘルプ出力は、オプションを Server Configuration セクションの下に明確に整理します：

Demo app showcasing labeled merge groups
Usage: [1mdemo-merge.ts[0m [3m--host[0m [4m[2mSTRING[0m [3m--port[0m [4m[2mINTEGER[0m [3m--timeout[0m [4m[2mINTEGER[0m [3m--retries[0m
       [4m[2mINTEGER[0m

Server Configuration:
  [3m--host[0m [4m[2mSTRING[0m               Server hostname or IP address
  [3m--port[0m [4m[2mINTEGER[0m              Port number for the connection
  [3m--timeout[0m [4m[2mINTEGER[0m           Connection timeout in seconds
  [3m--retries[0m [4m[2mINTEGER[0m           Number of retry attempts

新しい group() コンビネータ

merge() が適用できないケースでは、新しい group() コンビネータを使用して任意のパーサーをドキュメントラベルでラップできます：

// 相互に排他的なオプションを明確なセクションの下にグループ化
const outputFormat = group(
  "Output Format",
  or(
    map(flag("--json"), () => "json"),
    map(flag("--yaml"), () => "yaml"),
    map(flag("--xml"), () => "xml"),
  )
);

これは相互に排他的なフラグ、複数の入力、またはネイティブにラベル付けをサポートしていないパーサーを整理するのに特に役立ちます。結果として得られるヘルプテキストはより読みやすく、ユーザーフレンドリーになります。

グループ化された出力フォーマットオプションがヘルプテキストでどのように表示されるかは次のとおりです：

Demo app showcasing group combinator
Usage: [1mdemo-group.ts[0m [3m--json[0m
       [1mdemo-group.ts[0m [3m--yaml[0m
       [1mdemo-group.ts[0m [3m--xml[0m

Output Format:
  [3m--json[0m                      Output in JSON format
  [3m--yaml[0m                      Output in YAML format
  [3m--xml[0m                       Output in XML format

リッチなドキュメントサポート

Optique 0.4.0 では、run() 関数を通じて直接追加できる包括的なドキュメントフィールドが導入され、ドキュメント目的でパーサー定義を変更する必要がなくなりました。

簡潔な説明、詳細な解説、およびフッター

@optique/core/facade と @optique/run の両方が、run() 関数を通じて brief、description、および footer オプションをサポートするようになりました：

import { run } from "@optique/run";
import { message } from "@optique/core/message";

const result = run(parser, {
  brief: message`A powerful data processing tool`,
  description: message`This tool provides comprehensive data processing capabilities with support for multiple formats and transformations. It can handle JSON, YAML, and CSV files with automatic format detection.`,
  footer: message`Examples:
  myapp process data.json --format yaml
  myapp validate config.toml --strict

For more information, visit https://example.com/docs`,
  help: "option"
});

これらのドキュメントフィールドはヘルプ出力とエラーメッセージ（設定時）の両方に表示され、CLI のユーザーエクスペリエンス全体で一貫したコンテキストを提供します。

完全なヘルプ出力は、簡潔な説明、詳細な解説、オプションの説明、デフォルト値、およびフッター情報を含むリッチなドキュメント機能を示しています：

A powerful data processing tool
Usage: [1mdemo-rich-docs.ts[0m [2m[[0m[3m--port[0m [4m[2mINTEGER[0m[2m][0m [2m[[0m[3m--format[0m [4m[2mSTRING[0m[2m][0m [3m--verbose[0m [4m[2mSTRING[0m

This tool provides comprehensive data processing capabilities with support for
multiple formats and transformations. It can handle JSON, YAML, and CSV files
with automatic format detection.

  [3m--port[0m [4m[2mINTEGER[0m              Server port number[2m [3000][0m
  [3m--format[0m [4m[2mSTRING[0m             Output format[2m [json][0m
  [3m--verbose[0m [4m[2mSTRING[0m            Verbosity level

Examples:
  myapp process data.json --format yaml
  myapp validate config.toml --strict

For more information, visit https://example.com/docs

これらのドキュメントフィールドはヘルプ出力とエラーメッセージ（設定時）の両方に表示され、CLI のユーザーエクスペリエンス全体で一貫したコンテキストを提供します。

デフォルト値の表示

頻繁にリクエストされていた機能が利用可能になりました：ヘルプテキストに直接デフォルト値を表示します。withDefault() を使用する際に新しい showDefault オプションで有効にできます：

const parser = object({
  port: withDefault(
    option("--port", integer(), { description: message`Server port number` }),
    3000,
  ),
  format: withDefault(
    option("--format", string(), { description: message`Output format` }),
    "json",
  ),
});

run(parser, { showDefault: true });

// またはカスタムフォーマットで：
run(parser, {
  showDefault: {
    prefix: " (default: ",
    suffix: ")"
  }  // 表示例：--port (default: 3000)
});

デフォルト値は色が有効な場合、自動的に暗く表示され、視覚的に区別しつつも読みやすさを維持します。

ヘルプ出力では、各オプションの横にデフォルト値が明確にマークされて表示されます：

Usage: [1mdemo-defaults.ts[0m [2m[[0m[3m--port[0m [4m[2mINTEGER[0m[2m][0m [2m[[0m[3m--format[0m [4m[2mSTRING[0m[2m][0m

  [3m--port[0m [4m[2mINTEGER[0m              Server port number[2m [3000][0m
  [3m--format[0m [4m[2mSTRING[0m             Output format[2m [json][0m

Temporal API サポート

Optique 0.4.0 では、新しいパッケージ @optique/temporal が導入され、最新の Temporal API の包括的なサポートが提供されます。これにより、日付、時間、期間、タイムゾーンの型安全なパースが可能になります：

import { instant, duration, zonedDateTime } from "@optique/temporal";
import { option } from "@optique/core/parser";

const parser = object({
  // ISO 8601 タイムスタンプをパース
  timestamp: option("--at", instant()),

  // "PT30M" や "P1DT2H" のような期間をパース
  timeout: option("--timeout", duration()),

  // タイムゾーン情報付きの日時をパース
  meeting: option("--meeting", zonedDateTime()),
});

テンポラルパーサーは完全な機能を持つネイティブの Temporal オブジェクトを返します：

const result = parse(timestampArg, ["2023-12-25T10:30:00Z"]);
if (result.success) {
  const instant = result.value;
  console.log(`UTC: ${instant.toString()}`);
  console.log(`Seoul: ${instant.toZonedDateTimeISO("Asia/Seoul")}`);
}

新しいパッケージをインストールするには：

npm add @optique/temporal

型推論の改善

merge() コンビネータが最大10個のパーサー（以前は5個）をサポートするようになり、tuple() パーサーは TypeScript の const 型パラメータを使用して型推論が改善されました。これらの拡張により、完全な型安全性を維持しながら、より複雑な CLI 構造が可能になります。

破壊的変更

ほとんどの API の後方互換性を維持していますが、注意すべき変更がいくつかあります：

  • Parser.getDocFragments() メソッドが直接の状態値ではなく DocState<TState> を使用するようになりました（カスタムパーサー実装にのみ影響します）
  • merge() コンビネータがコンパイル時により厳格な型制約を適用し、オブジェクトを生成しないパーサーを拒否するようになりました

詳細情報

変更、バグ修正、改善の完全なリストについては、完全な変更ログを参照してください。

更新されたドキュメントをご覧ください：

インストール

Optique 0.4.0 にアップグレード：

npm update @optique/core @optique/run
# または
deno add jsr:@optique/core@^0.4.0 jsr:@optique/run@^0.4.0

テンポラルサポートの追加（オプション）：

npm add @optique/temporal
# または
deno add jsr:@optique/temporal

これらの改善により、Optique を使用した CLI アプリケーションの構築がさらに楽しくなることを願っています。いつものように、GitHub でのフィードバックと貢献をお待ちしています。

1
0
1

No comments

If you have a fediverse account, you can comment on this article from your own instance. Search https://hackers.pub/ap/articles/01991aa2-edea-797e-aad6-2f1ece168909 on your instance and reply to it.