`zenn-cli` パッケージの `/src/common/types.ts` で定義された型を公開して欲しい

[azrsh]

提案・要望

• SSIA

背景

• zenn-validator パッケージを Native ESM または CommonJS のモジュールとして import/require 可能な状態で公開して欲しい #479 によって zenn-validator を外部で利用しやすくなりますが、zenn-validator のバリデーションをパスしたオブジェクトを表現する型は外部に公開されていないため自前で型を定義する必要があります。
• zenn-cli が内部で使用している型定義を公開することでその必要を無くしたいです。

関連

• 型定義を公開する場合は、zenn-cli パッケージの下に公開するのではなく zenn-validator パッケージに型定義を移動して公開した方が良いのではないかと考えています。
• zenn-validator パッケージのバリデーション関数をユーザ定義 type guard として表現すれば TypeScript の型システムとバリデーションを統合できます。ただしこの場合は zenn-validator パッケージの API の破壊的変更が必要です。
• 受け入れてくださる場合は PR を作成します。

[uttk-dev]

@azarashi2931

いいと思います！
が、やはり破壊的変更がネックなので、少し開発チームに持ち帰って相談したいと思います。
なるべく早く回答できるように善処しますが、
時間がかかる場合がありますので、気長にお待ち頂ければと思います🙇‍♂️

[azrsh]

関連に書いたのはそういう方向もありうる、というだけの話なので、型定義だけでも公開してくださるとありがたいです！
よろしくお願いします。

[cm-wada-yusuke]

@uttk-dev さんから提案してもらいzenn-validator に型定義を寄せる方向で相談しました。ただ、 zenn-validator という名称の範疇を超えてしまいそうなので名前だけ変えさせてもらうかも知れません 🙏

[uttk-dev]

@azarashi2931

ありがとうございます。 @cm-wada-yusuke さんからもご連絡した通り、zenn-validator に型情報を寄せる方向で開発したいと思います。

それに伴い zenn-validator の名称を変更したいと思いますが、実際に名称変更するタイミングは、型情報を移植した後に行いたいと思いますので、もし Pull Request を作成してくださるのであれば、現状の zenn-validtor に対して作成して頂いて大丈夫です 🙆‍♂️

よろしくお願いします。

[azrsh]

PR は作成します。その前に方針についていくつか質問があります。

まず今回必要としている型情報は、例えば Article 型ではなく ArticleMeta 型のような、コンテンツのメタデータの型だけなのですが、zenn-validator にはメタデータの型のみを移植すべきですか？それとも両方の型定義を移動すべきですか？
https://github.com/zenn-dev/zenn-editor/blob/be511526b859feffa5012107421d24761cb3b5e9/packages/zenn-cli/src/common/types.ts#L3-L16
(zenn-validator ではテストコード以外で bodyHtml にアクセスする処理が現れないので、ZennValidator が扱う値の型はメタデータの型であると推測しました。https://github.com/zenn-dev/zenn-editor/blob/be511526b859feffa5012107421d24761cb3b5e9/packages/zenn-validator/__tests__/validator.test.ts#L11)

次に description の関連に書いた以下の変更はすべきですか？もししてもよいのであれば単に型定義を移動する PR とライブラリの API を変更する PR の 2 つを作成します。そうでない場合は前者の PR だけを作成します。

• zenn-validator パッケージのバリデーション関数をユーザ定義 type guard として表現すれば TypeScript の型システムとバリデーションを統合できます。ただしこの場合は zenn-validator パッケージの API の破壊的変更が必要です。

[azrsh]

また、この API の変更を実施する場合はどのような API デザインにするか決めたいです。

• ユーザ定義 type-guard で入力に対して型付をする。エラーは例外として投げる。
• description で書いたユーザ定義 type-guard を使うのではなく、バリデーション済の値またはエラーを表現する判別可能な union 型を返す。

[uttk-dev]

@azarashi2931

コメントありがとうございます。

まず今回必要としている型情報は、例えば Article 型ではなく ArticleMeta 型のような、コンテンツのメタデータの型だけなのですが、zenn-validator にはメタデータの型のみを移植すべきですか？それとも両方の型定義を移動すべきですか？ ( (zenn-validator ではテストコード以外で bodyHtml にアクセスする処理が現れないので、ZennValidator が扱う値の型はメタデータの型であると推測しました。)

現時点では、両方の型定義を移動すべきと考えています。両方が同じ場所にある方が管理しやすいと思いますし、Zenn の VSCode 拡張でも似たような型を定義してしまっているので、共通化してしまいたいです。

次に description の関連に書いた以下の変更はすべきですか？もししてもよいのであれば単に型定義を移動する PR とライブラリの API を変更する PR の 2 つを作成します。そうでない場合は前者の PR だけを作成します。

• zenn-validator パッケージのバリデーション関数をユーザ定義 type guard として表現すれば TypeScript の型システムとバリデーションを統合できます。ただしこの場合は zenn-validator パッケージの API の破壊的変更が必要です。

また、この API の変更を実施する場合はどのような API デザインにするか決めたいです。

• ユーザ定義 type-guard で入力に対して型付をする。エラーは例外として投げる。
• description で書いたユーザ定義 type-guard を使うのではなく、バリデーション済の値またはエラーを表現する判別可能な union 型を返す。

type-guard ではなく、型判別可能な union 型を返す方向で進めて頂けると嬉しいです！その場合、破壊的変更があっても問題ありません。イメージとしては以下のような感じです👇

type ValidateResult =
  | {
      success: true;
      value: ArticleMeta;
    }
  | {
      success: false;
      errors: ValidationError[];
    };

const validateArticle = ( value: any ): ValidateResult => { /* ... */ }

const result = validateArticle(anyValue);

if( result.success ) console.log( result.value ); // => ArticleMeta
else console.log( result.errors ) // => ValidationError[]

[azrsh]

型定義を移動するだけの PR を作成しました。レビューよろしくお願いします！

• Typecheck on build zenn-cli server zenn-editor#404
• Move contents type definition zenn-editor#405

[azrsh]

この PR がマージされた後に zenn-validator の API を変更する PR を作成します。

[uttk-dev]

@azarashi2931

Pull Request ありがとうございます！
zenn-dev/zenn-editor#404 の方はマージしました。
zenn-dev/zenn-editor#405 の方もレビューしましたが特に問題ないと思います！
よろしくお願いします！

[azrsh]

ありがとうございます！ zenn-dev/zenn-editor#405 の方も Ready for review にしました。よろしくお願いします！

[uttk-dev]

@azarashi2931

PR ありがとうございました 🙌
zenn-dev/zenn-editor#405 をマージしました！
正式なリリースについては来年になりそうなので、リリースされるまでは canary 版の方をご使用いただければと思います。
よろしくお願いします。

[uttk-dev]

@azarashi2931

zenn-dev/zenn-editor#409

上記の PR にて zenn-validator@v0.1.135 をリリースしましたので、こちらの Issue はクローズしたいと思います。
今後は最新版の方をご利用ください。

よろしくお願いします。