💡 Tentang mdz-env

mdz-env adalah sebuah utilitas JavaScript/TypeScript yang ringan dan type-safe untuk mem-parsing (mengurai) environment variables di aplikasi Node.js.

Seringkali, environment variables (seperti process.env.PORT atau process.env.DEBUG) selalu berupa string. mdz-env hadir untuk mempermudah Anda mengambil nilai-nilai ini dan mengkonversikannya ke tipe data yang benar (string, number, boolean) dengan aman, serta mendukung nilai default dan validasi required.

✨ Fitur Utama

Type-Safe: Otomatis mengkonversi string menjadi number atau boolean, dengan type inference yang tepat berkat TypeScript.

Default Values: Sediakan nilai default yang akan digunakan jika environment variable tidak ditemukan atau kosong.

Required Check: Dapatkan error langsung jika environment variable yang kritis tidak disetel.

Ringan: Tanpa dependencies eksternal, menjaga ukuran package tetap kecil.

Intuitive API: Desain API yang mudah dibaca dan digunakan.

🚀 Instalasi

Instal mdz-env ke proyek Anda menggunakan manajer package favorit Anda:

Menggunakan pnpm

pnpm add mdz-env

Menggunakan npm

npm install mdz-env

Menggunakan yarn

yarn add mdz-env

📖 Penggunaan (Usage)

Impor mdzEnv dan gunakan fungsi-fungsi string, number, atau boolean untuk mengambil environment variable Anda.

// app.ts atau config.ts
import { mdzEnv } from 'mdz-env';

// Mengambil string dengan nilai default
const NODE_ENV = mdzEnv.string('NODE_ENV', { defaultValue: 'development' });
console.log(`Aplikasi berjalan di mode: ${NODE_ENV}`); // Contoh: 'development' atau 'production'

// Mengambil angka dengan nilai default
const PORT = mdzEnv.number('PORT', { defaultValue: 3000 });
console.log(`Server mendengarkan di port: ${PORT}`); // Contoh: 3000 atau 8080

// Mengambil boolean (nilai 'true', '1', 'on' akan menjadi true, lainnya false)
const DEBUG_MODE = mdzEnv.boolean('DEBUG_MODE');
console.log(`Mode Debug: ${DEBUG_MODE ? 'Aktif' : 'Nonaktif'}`); // Contoh: true atau false

Opsi

required

Anda dapat menandai sebuah environment variable sebagai wajib (required: true). Jika variabel tersebut tidak ada atau kosong, mdz-env akan melempar error, yang membantu Anda menangani konfigurasi yang hilang sejak awal

import { mdzEnv } from 'mdz-env';

try {
  // Jika DB_HOST tidak disetel, ini akan melempar error
  const DB_HOST = mdzEnv.string('DB_HOST', { required: true });
  console.log('Database Host:', DB_HOST);

  const API_KEY = mdzEnv.string('API_KEY', { required: true });
  console.log('API Key:', API_KEY);

} catch (error: any) {
  console.error(`🚨 Kesalahan Konfigurasi: ${error.message}`);
  // Contoh output: "🚨 Kesalahan Konfigurasi: Environment variable "DB_HOST" is required but not set."
  process.exit(1); // Hentikan aplikasi jika konfigurasi kritis hilang
}

📦 API Referensi

Objek mdzEnv menyediakan tiga fungsi utama:

mdzEnv.string(key: string, options?: EnvOptions<string>): string

Mengambil environment variable sebagai string.

• key: Nama environment variable (misal: 'APP_NAME').

• options: Objek opsional dengan:

  • defaultValue?: string: Nilai yang akan dikembalikan - jika variabel tidak disetel atau kosong.
  • required?: boolean: Jika true, akan melempar error jika variabel tidak disetel atau kosong.

• Return: Nilai string dari variabel.

mdzEnv.number(key: string, options?: EnvOptions<number>): number

Mengambil environment variable sebagai number.

• key: Nama environment variable (misal: 'PORT').

• options: Objek opsional dengan:

  • defaultValue?: number: Nilai yang akan dikembalikan jika variabel tidak disetel.

  • required?: boolean: Jika true, akan melempar error jika variabel tidak disetel.

• Return: Nilai angka dari variabel.

• Catatan: Akan melempar error jika variabel disetel tetapi bukan angka yang valid.

mdzEnv.boolean(key: string, options?: EnvOptions<boolean>): boolean

Mengambil environment variable sebagai boolean.

• key: Nama environment variable (misal: 'DEBUG_MODE').

• Nilai yang dianggap true (case-insensitive): 'true', '1', 'on'.

• Semua nilai lain dianggap false (termasuk string kosong atau variabel yang tidak disetel).

• options: Objek opsional dengan:

  • defaultValue?: boolean: Nilai yang akan dikembalikan jika variabel tidak disetel atau kosong.

  • required?: boolean: Jika true, akan melempar error jika variabel tidak disetel atau kosong.

• Return: Nilai boolean dari variabel.

🤝 Kontribusi

Sangat disambut baik untuk berkontribusi pada proyek ini! Jika Anda menemukan bug atau memiliki ide untuk fitur baru, silakan buka issue atau buat pull request.

👨‍💻 Penulis

Muhammad Dariaz Zidane