circumspect

用心深い

circumspect TypeScript/JavaScript コードをより安全にするための関数のセットです。これらの関数には、 invariant 、 warning 、 assertNeverなどが含まれます。

なぜこのライブラリが存在するのでしょうか?

invariantやassertNeverなど、コードの安全性を高める便利な関数が多数あります。これらの関数の多くは、個別の npm パッケージ (例: invariant ) として利用できます。しかし、関数ごとに新しいパッケージ (そしてほとんどの場合、対応する@typesパッケージ) をインストールするのはあまり便利ではありません。また、これらのパッケージは通常、関数をデフォルトのエクスポートとしてエクスポートするため、VSCode の自動インポートがうまく機能しません。

このライブラリは、コードをより安全にする関数を 1 か所に統合​​します。 circumspectそれらすべてを含む単一の依存関係です。また、 circumspectによって提供されるすべての関数はエクスポートという名前が付けられているため、VSCode の自動インポートは期待どおりに機能します。

さらに、 circumspectは 100% TypeScript で書かれているため、すべての関数はデフォルトで適切に型付けされます。したがって、個別の@typesパッケージをインストールする必要はありません。

インストール

糸の使用:

 yarn add circumspect

npm の使用:

 npm install circumspect

API

• invariant
• warning
• assertNever
• nonNull

invariant

 invariant ( value : unknown , message ?: string ) : asserts value 

パラメータ

• value: unknown真実であることを確認したい値です。

• message?: string渡されたvalueが false の場合にスローされるエラーに含まれるオプションのエラー メッセージです。このカスタム エラー メッセージは開発中にのみ表示されます。運用環境では、代わりに一般的なエラー ( 'Invariant violation' ) が表示され、 messageパラメーターは無視されます。

戻り値

• asserts valueこれは、関数が単にvalueの型を真実になるように絞り込み、何も返さないことを意味します。

説明

invariant指定されたvalueが真実であることを保証します。そうでない場合は、指定されたmessageを含むエラーがスローされます (開発時のみ)。この関数は、すべての偽の値 (例: nullやundefined ) を除外することで、 valueのタイプを適切に絞り込みます。

invariant偽である可能性がある値を持っている場合には常に使用する必要がありますが、特定の状況では、その値は真実でなければならないと確信しています。つまり、値が真であるという事実は不変条件であり、値が偽である場合は不変条件に違反しているため、エラーをスローする必要があります。

message引数は運用環境では完全に無視されるため、運用ビルドではコードからメッセージ引数を完全に削除することをお勧めします。その方法については、「最適化」セクションを参照してください。

例

 declare const user : User | null | undefined ;

invariant ( user , 'The user is missing!' ) ;

user ; // If we get here, the type is narrowed to `User`

この例では、 userオブジェクトは潜在的にnullまたはundefined (つまり false) になる可能性があります。その場合は、不変条件違反があり、 invariant関数がスローされます。それ以外の場合は、単に戻り、 user実際にユーザー オブジェクトを指していることがわかります。

warning

 warning ( value : unknown , message : string ) : void 

パラメータ

• value: unknown確認したい値です。偽の場合は、コンソールに警告が発行されます。

• message: stringコンソールに書き込まれる警告メッセージです。

戻り値

• void関数は何も返しません。

説明

warning指定されたvalueが false の場合、指定されたmessageとともにコンソールに警告を発行します。警告は開発中にのみ発行されます。運用環境では、この関数は何も行いません。

これは、値が間違っている場合に開発専用の警告を発行する場合に常に使用する必要があります。これは、警告メッセージで報告されている重大ではない問題を開発者が修正できるようにするのに役立ちます。

実稼働環境ではwarning何も行わないため、実稼働ビルドではコードからこの関数の呼び出しを完全に削除することをお勧めします。その方法については、「最適化」セクションを参照してください。

例

 declare const mode : 'auto' | 'default' | 'slow' | 'fast' ;

warning (
  mode !== 'auto' ,
  'Mode "auto" has been deprecated. Please use "default" instead.' ,
) ;

この例では、 modeが'auto'の場合に非推奨の警告を発行したいと考えています。そのためには、 false の値を渡す必要があります。そのため、 mode !== 'auto'を渡します。これは、 modeが'auto'の場合にのみ false になります。

場合によっては、 false直接渡すことが合理的です。例えば：

 declare const languages : Language [ ] ;
declare const defaultLanguage : Language ;
declare const langName : string ;

let lang = languages . find ( ( { name } ) => name === langName ) ;

if ( ! lang ) {
  warning (
    false ,
    `Language with name " ${ langName } " not found. Falling back to the default language.` ,
  ) ;

  lang = defaultLanguage ;
}

assertNever

 assertNever ( value : never ) : never

パラメータ

• value: never考えられる共用体型のバリアントをすべて使い果たした後の値です。

戻り値

• never 、関数が決して戻らないことを意味します。実際に呼び出されるとエラーがスローされるだけです。

説明

共用体型のすべてのバリアントを確実に使い果たすために、 assertNever使用する必要があります。

valueのすべての共用体バリアントが使い尽くされている場合、 valueを指定してassertNeverを呼び出してもコンパイラ エラーは発生しません。これは、その時点ではvalue never型とみなされ、実行時には、 assertNever呼び出す時点に到達することはありません。エラーはスローされません。

ただし、すべての共用体バリアントが使い尽くされていない場合は、 never以外の値でassertNever呼び出しているため、次のようなコンパイラ エラーが発生します。

 Argument of type 'x' is not assignable to parameter of type 'never'.

これは、欠落しているバリアントを処理することで修正できます。共用体の網羅性チェックとassertNeverの詳細については、TypeScriptのドキュメントを参照してください。

例

 declare const state : 'loading' | 'done' | 'error' ;

switch ( state ) {
  case 'loading' :
    return < Loading / > ;
  case 'done' :
    return < Done / > ;
  case 'error' :
    return < Error / > ;
}

この例では、 switchステートメント内のすべての可能な状態 ( 'loading' 、 'done' 、および'error'を処理します。

ただし、将来的に'pending'などの別の状態を追加した場合はどうなるでしょうか?

switchステートメントが'pending'を処理していないという事実は検出されません。

解決策は、すべての可能な状態が処理されたと主張するdefaultケースを用意することです。

 switch ( state ) {
  ...
  default :
    return assertNever ( state ) ;
}

したがって、すべての状態バリアントが処理される場合、コンパイル時エラーは発生しません。ただし、新しい'pending'状態を追加すると、次のようなコンパイラ エラーが発生します。

 Argument of type 'string' is not assignable to parameter of type 'never'.

このエラーは、 switch内で'pending'状態を処理することで修正できます。

この例からわかるように、 assertNever考えられるすべてのケースを常に確実に処理する必要があるswitchステートメントで特に役立ちます。

nonNull

 nonNull < T > ( value : T | null | undefined ) : value is T 

パラメータ

• value: T | null | undefined nullまたはundefinedでないことを確認する値です。

戻り値

• value is Tこれは、関数が渡された値がnullまたはundefinedないかどうかを示すブール値を返すことを意味します。これにより、 trueが返された場合、 valueの型がTに絞り込まれます (つまり、 nullとundefinedが除外されます)。

説明

nonNullは、指定された値が非 null であるかどうか、つまりnullでもundefinedでもないかどうかをチェックする述語関数です。関数を呼び出した後、返されたtrueまたはfalseに基づいてvalueの型が適切に絞り込まれます。

nonNull 、潜在的にnull 、 undefined 、またはその両方である可能性のある値があり、それをチェックしてその型を適切に絞り込みたい場合に使用する必要があります。

この関数の名前は、 NonNullableユーティリティ タイプに由来しており、タイプからnullとundefined除外します。

例

 declare const names : ( string | null ) [ ] ;

const nonNullNames = names . filter ( nonNull ) ;

// nonNullNames has type 'string[]'

この例では、いくつかのnull要素も含めることができる名前の配列があります。すべての非 null 要素の配列をフィルターし、 string[]返します。

代わりにnames.filter(x => x !== null)を使用すると、null 以外の要素が返されますが、TypeScript はfilterに渡す関数を認識するため、型は(string | null)[]のままになります。 booleanを返すだけなので、型の絞り込みは行われません。

最適化

babel-plugin-dev-expression使用して、 invariantに渡されるmessage引数を削除し、本番環境でのwarningの呼び出しを完全に削除することをお勧めします。

基本的に、運用環境では、 babel-plugin-dev-expressionが

 invariant ( value , 'Value is falsy!' ) ;

と

 if ( ! value ) {
  invariant ( false ) ;
}

したがって、 message引数は削除されます。また、 warningへの呼び出しも完全に削除されます。したがって、次のような行

 warning ( value , 'Value is falsy!' ) ;

が削除されます。

貢献する

プルリクエストは大歓迎です。大きな変更を導入する場合は、まず関連する問題を開いて、変更したい内容について話し合ってください。

必要に応じてテストと README を更新してください。

ライセンス

マサチューセッツ工科大学