circumspect

berhati-hati

circumspect adalah serangkaian fungsi untuk membuat kode TypeScript/JavaScript Anda lebih aman. Fungsi-fungsi ini mencakup invariant , warning , assertNever , dan banyak lagi.

Mengapa perpustakaan ini ada?

Ada banyak fungsi bermanfaat yang dapat membuat kode Anda lebih aman, seperti invariant assertNever . Banyak dari fungsi ini tersedia sebagai paket npm terpisah (misalnya, invariant ). Tetapi menginstal paket baru (dan seringkali paket @types juga) untuk setiap fungsi sangatlah tidak nyaman. Selain itu, paket-paket tersebut umumnya mengekspor fungsinya sebagai ekspor default, sehingga impor otomatis VSCode tidak berfungsi dengan baik.

Pustaka ini menyatukan fungsi-fungsi yang membuat kode Anda lebih aman ke dalam satu tempat. circumspect adalah ketergantungan tunggal yang memiliki semuanya. Dan impor otomatis VSCode berfungsi seperti yang diharapkan karena semua fungsi yang disediakan oleh circumspect diberi nama ekspor.

Selain itu, circumspect 100% ditulis dalam TypeScript, sehingga setiap fungsi diketik dengan benar secara default. Jadi, tidak perlu menginstal paket @types terpisah.

Instalasi

Menggunakan benang:

 yarn add circumspect

Menggunakan npm:

 npm install circumspect

API

• invariant
• warning
• assertNever
• nonNull

invariant

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

Parameter

• value: unknown adalah nilai yang ingin kami pastikan kebenarannya.

• message?: string adalah pesan kesalahan opsional yang akan disertakan dalam kesalahan yang muncul ketika value yang diteruskan salah. Pesan kesalahan khusus ini hanya ditampilkan dalam pengembangan. Dalam produksi, kesalahan umum ditampilkan ( 'Invariant violation' ) dan parameter message diabaikan.

Nilai kembalian

• asserts value yang berarti bahwa fungsi tersebut hanya mempersempit jenis value menjadi benar dan tidak mengembalikan apa pun.

Keterangan

invariant memastikan bahwa value yang ditentukan benar. Jika bukan itu masalahnya, ia akan memunculkan kesalahan yang berisi message tertentu (hanya dalam pengembangan). Fungsi ini secara tepat mempersempit jenis value dengan mengecualikan semua nilai yang salah (misal, null dan undefined ).

invariant harus digunakan setiap kali kita memiliki nilai yang berpotensi salah, namun kami yakin bahwa dalam keadaan tertentu, nilai tersebut harus benar. Artinya, fakta bahwa nilai tersebut benar adalah sebuah invarian, dan jika suatu saat nilainya salah, maka invarian tersebut telah dilanggar, dan dengan demikian kesalahan harus terjadi.

Karena argumen message sepenuhnya diabaikan dalam produksi, Anda mungkin ingin menghapusnya dari kode Anda sepenuhnya dalam build produksi. Untuk mengetahui cara melakukannya, lihat bagian Pengoptimalan.

Contoh

 declare const user : User | null | undefined ;

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

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

Dalam contoh ini, objek user berpotensi menjadi null atau undefined (yaitu, salah). Jika demikian, kita mengalami pelanggaran invarian, dan fungsi invariant akan hilang. Jika tidak, ia akan kembali dan kita tahu bahwa user sebenarnya menunjuk ke objek pengguna.

warning

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

Parameter

• value: unknown adalah nilai yang ingin kita periksa. Jika salah, peringatan dikeluarkan ke konsol.

• message: string adalah pesan peringatan yang akan ditulis ke konsol.

Nilai kembalian

• void fungsinya tidak mengembalikan apa pun.

Keterangan

warning mengeluarkan peringatan ke konsol dengan message yang diberikan jika value yang ditentukan salah. Peringatan ini dikeluarkan hanya dalam pengembangan. Dalam produksi, fungsi ini tidak melakukan apa pun.

Ini harus digunakan kapan pun kita ingin mengeluarkan peringatan khusus pengembangan jika ada nilai yang salah, yang akan membantu memandu pengembang untuk memperbaiki masalah tidak kritis yang dilaporkan dalam pesan peringatan.

Karena warning tidak berpengaruh apa pun dalam produksi, Anda mungkin ingin menghapus panggilan ke fungsi ini sepenuhnya dari kode Anda di build produksi. Untuk mengetahui cara melakukannya, lihat bagian Pengoptimalan.

Contoh

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

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

Dalam contoh ini, kami ingin mengeluarkan peringatan penghentian jika mode adalah 'auto' . Untuk melakukannya, kita perlu memberikan nilai falsy, itu sebabnya kita meneruskan mode !== 'auto' , yang falsy hanya jika mode adalah 'auto' .

Dalam beberapa kasus, masuk akal untuk menyampaikan false secara langsung. Misalnya:

 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

Parameter

• value: never merupakan nilai setelah semua varian jenis gabungan yang mungkin telah habis.

Nilai kembalian

• never yang berarti fungsi tersebut tidak pernah kembali; itu hanya menimbulkan kesalahan jika benar-benar dipanggil.

Keterangan

assertNever harus digunakan untuk memastikan bahwa semua varian tipe gabungan telah habis.

Jika semua varian gabungan value telah habis, tidak ada kesalahan kompiler saat memanggil assertNever dengan value , karena value dianggap bertipe never pada saat itu, dan pada saat run time, kita tidak pernah mencapai titik memanggil assertNever , yang berarti bahwa tidak ada kesalahan yang akan terjadi.

Namun, jika tidak semua varian gabungan telah habis, maka kami memanggil assertNever dengan sesuatu selain never sehingga akan ada kesalahan kompiler yang mengatakan sesuatu seperti

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

yang dapat kami perbaiki dengan menangani varian yang hilang. Anda dapat membaca lebih lanjut tentang pemeriksaan kelengkapan serikat pekerja dan assertNever di dokumen TypeScript.

Contoh

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

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

Dalam contoh ini, kami menangani semua kemungkinan status di dalam pernyataan switch : 'loading' , 'done' , dan 'error' .

Namun, bagaimana jika di kemudian hari kita menambahkan status lain, misalnya 'pending' ?

Fakta bahwa pernyataan switch tidak menangani 'pending' tidak akan terdeteksi.

Solusinya adalah dengan memiliki kasus default yang menyatakan bahwa semua kemungkinan status telah ditangani.

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

Jadi, ketika semua varian negara ditangani, kami tidak mendapatkan kesalahan waktu kompilasi. Namun, ketika kita menambahkan status 'pending' baru, kita akan mendapatkan kesalahan kompiler yang mengatakan:

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

Kita dapat memperbaiki kesalahan ini dengan menangani status 'pending' di dalam switch .

Seperti yang dapat Anda lihat dari contoh ini, assertNever sangat berguna dalam pernyataan switch di mana kami ingin memastikan bahwa kami telah menangani semua kasus yang mungkin terjadi setiap saat.

nonNull

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

Parameter

• value: T | null | undefined adalah nilai yang ingin kita periksa apakah bernilai null atau undefined .

Nilai kembalian

• value is T yang berarti fungsi mengembalikan boolean yang menunjukkan apakah nilai yang diteruskan bukan null atau undefined . Ini mempersempit tipe value menjadi T (yaitu, mengecualikan null dan undefined ) ketika true dikembalikan.

Keterangan

nonNull adalah fungsi predikat yang memeriksa apakah nilai yang ditentukan adalah non-null, yaitu null atau undefined . Setelah memanggil fungsi, jenis value dipersempit dengan benar berdasarkan apakah true atau false yang dikembalikan.

nonNull harus digunakan setiap kali kita memiliki nilai yang berpotensi berupa null , undefined , atau keduanya dan kita ingin memeriksanya dan mempersempit tipenya dengan benar.

Nama fungsi ini berasal dari tipe utilitas NonNullable , yang mengecualikan null dan undefined dari suatu tipe.

Contoh

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

const nonNullNames = names . filter ( nonNull ) ;

// nonNullNames has type 'string[]'

Dalam contoh ini, kita memiliki array nama yang juga dapat menyertakan beberapa elemen null . Kami memfilter array untuk semua elemen non-null dan mendapatkan kembali string[] .

Jika kita menggunakan names.filter(x => x !== null) , kita akan mendapatkan kembali elemen non-null, tetapi tipenya akan tetap (string | null)[] karena TypeScript melihat fungsi yang kita teruskan untuk filter seperti hanya mengembalikan boolean sehingga tidak terjadi penyempitan tipe.

Pengoptimalan

Kami merekomendasikan penggunaan babel-plugin-dev-expression untuk menghapus argumen message yang diteruskan ke invariant dan untuk sepenuhnya menghapus panggilan ke warning dalam produksi.

Pada dasarnya, dalam produksi, babel-plugin-dev-expression menggantikan

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

dengan

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

jadi argumen message dihilangkan. Ini juga sepenuhnya menghilangkan panggilan untuk warning . Jadi, garisnya seperti ini

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

dihapus.

Berkontribusi

Permintaan tarik sangat diterima. Jika Anda berniat melakukan perubahan besar, silakan buka terbitan terkait terlebih dahulu sehingga kita dapat mendiskusikan apa yang ingin Anda ubah.

Harap pastikan untuk memperbarui tes dan README sebagaimana mestinya.

Lisensi

MIT