iodine

Yodium

Iodine.js adalah perpustakaan validasi sisi klien mikro. Ia tidak memiliki ketergantungan dan dapat digunakan secara terpisah atau sebagai bagian dari kerangka kerja. Yodium juga mendukung aturan yang dapat dirantai, memungkinkan Anda memverifikasi bahwa suatu bagian (atau beberapa bagian) data memenuhi beberapa kriteria.

Perbaikan

Yodium versi 8+ melibatkan penulisan ulang besar-besaran dengan banyak perubahan yang dapat mengganggu. Oleh karena itu disarankan agar proyek yang ada tetap menggunakan versi 7 (atau lebih rendah), sedangkan versi 8 (atau lebih tinggi) sebaiknya dicadangkan untuk proyek yang lebih baru.

Instalasi

Cara termudah untuk memasukkan Iodine ke dalam proyek Anda adalah melalui CDN (pastikan untuk memperbarui nomor build):

 < script src =" https://cdn.jsdelivr.net/npm/@caneara/[email protected]/dist/iodine.min.umd.js " defer >  script >

Anda juga dapat menarik Yodine ke dalam proyek Anda melalui NPM:

 npm i @ caneara / iodine 

Penggunaan

Yodium secara otomatis ditambahkan ke namespace window , membuatnya tersedia di mana saja. Ini adalah cara yang disarankan untuk menggunakan Yodium jika proyek Anda tidak melibatkan kompilasi atau impor. Bahkan jika proyek Anda melibatkan kompilasi, seringkali lebih mudah untuk hanya menggunakan instance yang ditambahkan ke namespace window .

Alternatifnya, jika Anda merasa nyaman menggunakan impor, atau ingin membuat instance Anda sendiri, Anda dapat mengimpor Iodine seperti ini:

 import Iodine from '@caneara/iodine' ;

const instance = new Iodine ( ) ; 

Validasi Dasar

Yodium menyertakan sekumpulan aturan validasi yang dapat Anda akses melalui metode terkait. Hal ini membuatnya cepat dan mudah untuk memeriksa apakah suatu item, misalnya, bilangan bulat atau tanggal.

Aturan Yodium diawali dengan assert . Jadi, untuk memeriksa apakah suatu item adalah integer , Anda akan menggunakan kode berikut:

 let item_1 = 7 ;
let item_2 = 'string' ;

Iodine . assertInteger ( item_1 ) ; // true
Iodine . assertInteger ( item_2 ) ; // false

Lihat di bawah untuk daftar lengkap aturan validasi Iodine yang disertakan.

Validasi Lanjutan

Meskipun memeriksa apakah suatu item mematuhi aturan validasi individual dapat berguna, Anda sering kali ingin memeriksa apakah suatu item mematuhi beberapa aturan. Misalnya, alamat email mungkin diperlukan, harus berupa string, dan harus memenuhi ekspresi reguler alamat email.

Untuk memenuhi kebutuhan ini, Iodine menawarkan 'pemeriksaan satu item' dan 'pemeriksaan beberapa item'...

Pemeriksaan Item Tunggal

Pendekatan ini lebih disukai jika Anda memiliki satu item yang perlu diuji berdasarkan beberapa aturan (seperti contoh alamat email yang dijelaskan di atas). Untuk melakukan 'pemeriksaan item tunggal', panggil metode assert utama. Metode ini mengambil dua parameter. Yang pertama, adalah item yang harus diperiksa. Yang kedua, adalah array aturan validasi yang harus dijalankan secara berurutan, misalnya

 let item_1 = 7 ;
let item_2 = 'string' ;

Iodine . assert ( item_1 , [ 'required' , 'integer' ] ) ;
Iodine . assert ( item_2 , [ 'required' , 'integer' ] ) ;

Seperti yang Anda lihat pada contoh, aturan validasi dinyatakan menggunakan strings . Untuk menemukan representasi string untuk aturan validasi, tinjau daftar yang ada.

Berbeda dengan pernyataan individual (yang mengembalikan boolean ), metode assert mengembalikan object yang berisi laporan. Ketika item melewati semua aturan, Anda akan mendapatkan ini:

 {
    valid : true ,
    rule  : '' ,
    error : '' ,
} ;

Jika item gagal divalidasi, laporan akan berisi aturan pertama yang gagal dipenuhi, bersama dengan pesan kesalahan terkait:

 {
    valid : false ,
    rule  : 'integer' ,
    error : 'Value must be an integer' ,
} ;

Pemeriksaan Beberapa Item

Pendekatan ini lebih disukai ketika Anda perlu memeriksa beberapa item terhadap sekumpulan aturan validasi yang berbeda, misalnya ketika mengirimkan formulir yang berisi beberapa bidang.

Seperti halnya 'pemeriksaan item tunggal', Anda harus memanggil metode assert , namun untuk kedua parameter, Anda perlu menyediakan object . Objek pertama harus berisi item yang akan divalidasi, sedangkan objek kedua harus berisi aturan untuk setiap item, misalnya

 const items = {
    name     : 5 ,
    email    : '[email protected]' ,
    password : 'abcdefgh' ,
} ;

const rules = {
    name     : [ 'required' , 'string' ] ,
    email    : [ 'required' , 'email' ] ,
    password : [ 'required' ] ,
} ;

Iodine . assert ( items , rules ) ;

Berbeda dengan 'pemeriksaan item tunggal', laporannya sedikit berbeda. Ini berisi kunci valid tingkat atas yang memungkinkan Anda memeriksa dengan mudah apakah semuanya berhasil atau ada yang gagal. Kemudian berisi kunci fields , yang berisi sub-laporan untuk setiap item. Sub-laporan adalah hal yang sama yang Anda dapatkan untuk 'pemeriksaan item tunggal'. Berikut laporan untuk contoh kode yang ditunjukkan di atas:

 {
    valid  : false ,
    fields : {
        name : {
            valid : false ,
            rule  : 'string' ,
            error : 'Value must be a string' ,
        } ,
        email : {
            valid : true ,
            rule  : '' ,
            error : '' ,
        } ,
        password : {
            valid : true ,
            rule  : '' ,
            error : '' ,
        }
    } ,
} ; 

Parameter tambahan

Beberapa aturan memerlukan parameter tambahan, misalnya

 let item_1 = 7 ;
let item_2 = 4 ;

Iodine . assertMin ( item_1 , 5 ) ; // true
Iodine . assertMin ( item_2 , 5 ) ; // false

Untuk validasi tingkat lanjut, Anda dapat menyediakan parameter dengan menambahkannya ke aturan dengan pemisah titik koma, misalnya

 let item_1 = 7 ;
let item_2 = 4 ;

Iodine . assert ( item_1 , [ 'required' , 'integer' , 'min:5' ] ) ;
Iodine . assert ( item_2 , [ 'required' , 'integer' , 'min:5' ] ) ;

Atau, jika mau, Anda dapat menyediakan aturan sebagai object bukan string yang dipisahkan dengan titik koma:

 Iodine . assert ( 8 , [ 'required' , 'integer' , { rule : 'min' , param : 7 } , 'max:10' ] ) ; 

Nilai opsional

Untuk validasi tingkat lanjut, Anda mungkin ingin mengizinkan nilai opsional. Yodium mendukung hal ini dengan aturan optional :

 let item_1 = 7 ;
let item_2 = null ;
let item_3 = 'string' ;

Iodine . assert ( item_1 , [ 'optional' , 'integer' ] ) ;
Iodine . assert ( item_2 , [ 'optional' , 'integer' ] ) ;
Iodine . assert ( item_3 , [ 'optional' , 'integer' ] ) ;

PENTING : Jika Anda ingin mengizinkan nilai opsional, maka nilai tersebut harus menjadi aturan pertama dalam array.

Kesalahan Khusus

Yodium menyertakan serangkaian pesan kesalahan default untuk bahasa Inggris. Namun, Anda dapat dengan mudah menggantinya melalui metode setErrorMessages . Metode ini memerlukan satu parameter, yaitu object yang berisi pesan. Lihat konstruktor Yodium sebagai contoh.

Yodium akan secara otomatis menggantikan placeholder [FIELD] dan [PARAM] ketika terjadi kesalahan. Oleh karena itu, Anda harus memasukkan placeholder ini pada posisi yang sesuai dalam pesan kesalahan baru Anda, misalnya

 Iodine . setErrorMessages ( { same : `[FIELD] must be '[PARAM]'` } ) ;   // English
Iodine . setErrorMessages ( { same : `[FIELD] doit être '[PARAM]'` } ) ; // French

Kesalahan Tunggal

Dalam banyak kasus, Anda tidak perlu mengganti semua pesan kesalahan. Anda malah ingin memperbarui satu atau menambahkan yang baru. Untuk melakukan itu, Anda sebaiknya memanggil setErrorMessage misalnya

 Iodine . setErrorMessage ( 'passwordConfirmation' , 'Does not match password' ) ;

Kesalahan Khusus berdasarkan Bidang

Terkadang, mungkin perlu untuk menentukan pesan kesalahan tertentu untuk suatu bidang, atau Anda memerlukan label untuk bidang yang berbeda dari nama variabel yang digunakan.

Untuk mencapai hal ini, teruskan objek ke metode assert yang berisi aturan sebagai properti dan pesan kesalahan khusus sebagai nilai misalnya

 Iodine . assert ( value , [ 'required' ] , { 'required' : 'The "Label" must be present.' } ) ;

Anda juga dapat menggunakan pendekatan yang sama untuk beberapa bidang misalnya

 let items = {
    name : '' ,
} ;

let rules = {
    name : [ 'required' ]
} ;

let errors = {
    name : {
        required : 'The "Label" must be present.'
    }
} ;

Iodine . assert ( items , rules , errors ) ;

Nama bidang bawaan

Karena 'pemeriksaan item tunggal' tidak mendukung nama bidang, Iodine menggunakan default (yaitu 'Nilai'). Jika 'Nilai' tidak sesuai, Anda dapat memanggil metode setDefaultFieldName dan memberikan nilai string alternatif untuk digunakan, misalnya

 Iodine . setDefaultFieldName ( 'Valeur' ) ;

Perhatikan bahwa Anda harus memanggil setDefaultFieldName sebelum menelepon assert .

Aturan yang tersedia

Aturan validasi berikut tersedia:

Aturan	Kunci Tali	Keterangan
tegaskanSetelah(tanggal/bilangan bulat)	'setelah'	Verifikasi bahwa item tersebut adalah Date setelah Date atau stempel waktu tertentu
menegaskanAfterOrEqual(tanggal/bilangan bulat)	'setelahOrEqual'	Verifikasi bahwa item tersebut adalah Date setelah atau sama dengan Date atau stempel waktu tertentu
menegaskanArray	'susunan'	Verifikasi bahwa item tersebut adalah array
menegaskanSebelum(tanggal/bilangan bulat)	'sebelum'	Verifikasi bahwa item tersebut adalah Date sebelum Date atau stempel waktu tertentu
menegaskanBeforeOrEqual(tanggal/bilangan bulat)	'sebelum Atau Sama Dengan'	Verifikasi bahwa item tersebut adalah Date sebelum atau sama dengan Date atau stempel waktu tertentu
menegaskanBoolean	'boolean'	Verifikasi apakah item tersebut true atau false
menegaskanTanggal	'tanggal'	Verifikasi bahwa item tersebut adalah objek Date
menegaskanDifferent(nilai)	'berbeda'	Verifikasi bahwa item tersebut berbeda dengan nilai yang diberikan (menggunakan perbandingan longgar)
menegaskanEnds(nilai)	'berakhir'	Verifikasi bahwa item diakhiri dengan nilai yang diberikan
menegaskanEmail	'e-mail'	Verifikasi bahwa item tersebut adalah alamat email yang valid
tegaskan Falsy	'salah'	Verifikasikan apakah itemnya false , 'false' , 0 atau '0'
tegaskan(array)	'di dalam'	Verifikasi bahwa item tersebut berada dalam array yang diberikan
menegaskanInteger	'bilangan bulat'	Verifikasi bahwa item tersebut adalah integer
tegaskanJson	'json'	Verifikasi bahwa item tersebut adalah string objek JSON yang dapat diurai
menegaskanMaxLength(batas)	'Panjang maksimal'	Pastikan panjang karakter item tidak melebihi batas yang diberikan
menegaskanMinLength(batas)	'panjang menit'	Pastikan panjang karakter item tidak berada di bawah batas yang diberikan
menegaskanMax(batas)	'maks'	Pastikan nilai numerik item tidak melebihi batas yang diberikan
menegaskanMin(batas)	'menit'	Pastikan nilai numerik item tidak berada di bawah batas yang diberikan
menegaskanNotIn(array)	'tidak masuk'	Verifikasi bahwa item tersebut tidak berada dalam array yang diberikan
menegaskanNumerik	'numerik'	Verifikasi bahwa item tersebut berupa number atau string numerik
menegaskanOpsional	'opsional'	Izinkan nilai opsional (hanya untuk digunakan dengan beberapa pemeriksaan)
tegaskanRegexMatch(exp)	'Pertandingan reguler'	Verifikasi bahwa item tersebut memenuhi ekspresi reguler yang diberikan
menegaskan Diperlukan	'diperlukan'	Verifikasi bahwa item tersebut bukan null , undefined , atau string kosong
menegaskanSama(nilai)	'sama'	Verifikasi bahwa item tersebut sama dengan nilai yang diberikan (menggunakan perbandingan longgar)
menegaskanMulaiDengan(nilai)	'dimulai dengan'	Verifikasi bahwa item dimulai dengan nilai yang diberikan
menegaskanString	'rangkaian'	Verifikasi bahwa item tersebut adalah string
menegaskan Kebenaran	'jujur'	Verifikasikan apakah item tersebut true , 'true' , 1 atau '1'
menegaskanUrl	'url'	Verifikasi bahwa item tersebut adalah URL yang valid
tegaskanUuid	'uuid'	Verifikasi bahwa item tersebut adalah UUID

Periksa tes untuk contoh bagaimana menggunakan setiap aturan.

Aturan adat

Yodium memungkinkan Anda menambahkan aturan validasi khusus Anda sendiri melalui metode rule . Metode ini menerima dua parameter. Yang pertama adalah nama aturannya. Yang kedua, adalah closure yang harus dilakukan Iodine ketika memanggil aturan misalnya

 Iodine . rule ( 'lowerCase' , ( value ) => value === value . toLowerCase ( ) ) ;

PENTING : Yodium secara otomatis akan menjadikan huruf pertama nama aturan menjadi huruf besar dan mengawalinya dengan 'assert'. Oleh karena itu, Anda sebaiknya menghindari menambahkan awalan sendiri, misalnya

 Iodine . rule ( 'lowerCase' ) ;       // right
Iodine . rule ( 'assertLowerCase' ) ; // wrong

Jika aturan Anda perlu menerima parameter, cukup sertakan parameter tersebut dalam closure Anda sebagai argumen kedua, misalnya

 Iodine . rule ( 'equals' , ( value , param ) => value == param ) ;

Anda juga dapat menambahkan pesan kesalahan untuk aturan khusus Anda, misalnya

 Iodine . rule ( 'equals' , ( value , param ) => value == param ) ;
Iodine . setErrorMessage ( 'equals' , "[FIELD] must be equal to '[PARAM]'" ) ; 

Aturan asinkron

Versi Iodine sebelumnya mendukung aturan khusus asinkron menggunakan async / await . Ini telah dihapus untuk membuat perpustakaan lebih mudah dipelihara. Jika Anda menggunakan aturan asynchronous, maka strategi pilihannya adalah mengeksekusi logika asynchronous Anda terlebih dahulu, menyimpan hasilnya, dan kemudian meminta Iodine memvalidasinya.

Berkontribusi

Terima kasih telah mempertimbangkan kontribusi untuk Yodium. Anda dipersilakan untuk mengirimkan PR yang berisi aturan tambahan, namun untuk diterima, PR tersebut harus menjelaskan fungsinya, bermanfaat bagi orang lain, dan menyertakan tes yang sesuai untuk memastikan bahwa PR tersebut berfungsi dengan benar.

Setelah menarik proyek, untuk menginstal dependensi:

npm install

Untuk menjalankan tes

npm run test 

Lisensi

Lisensi MIT (MIT). Silakan lihat File Lisensi untuk informasi lebih lanjut.