baher-dotenv

Type-safe environment configuration loader for Node.js.

🇺🇸 English

Overview

baher-dotenv is a TypeScript library for Node.js backend applications.

It allows you to define environment variables using a typed configuration object, then load these values into process.env.

The main goal is to make environment configuration more structured, centralized, and type-safe.

Installation

npm install baher-dotenv

Usage

import { baherEnvConfig, baherLoadEnv, ENV_TYPE } from 'baher-dotenv';

const envConfig = baherEnvConfig({
  APP_NAME: {
    type: ENV_TYPE.String,
    value: 'orders-api',
  },

  APP_PORT: {
    type: ENV_TYPE.Number,
    value: 3000,
  },

  ENABLE_ELK: {
    type: ENV_TYPE.Boolean,
    value: true,
  },
});

baherLoadEnv(envConfig);

After calling baherLoadEnv, the values will be available inside process.env:

process.env.APP_NAME;   // "orders-api"
process.env.APP_PORT;   // "3000"
process.env.ENABLE_ELK; // "true"

API

ENV_TYPE

A constant object used to define the type of each environment variable.

ENV_TYPE.String
ENV_TYPE.Number
ENV_TYPE.Boolean

baherEnvConfig(config)

Defines a typed environment configuration.

const envConfig = baherEnvConfig({
  APP_PORT: {
    type: ENV_TYPE.Number,
    value: 3000,
  },
});

If the value does not match the selected type, TypeScript will show an error.

Example:

const envConfig = baherEnvConfig({
  APP_PORT: {
    type: ENV_TYPE.Number,
    value: '3000', // TypeScript error
  },
});

baherLoadEnv(config, options?)

Loads the provided configuration into process.env.

baherLoadEnv(envConfig);

By default, existing values inside process.env are not overwritten.

To allow overriding existing values:

baherLoadEnv(envConfig, {
  override: true,
});

Supported Types

Currently supported types:

string
number
boolean

All values are converted to strings before being added to process.env, because Node.js environment variables are string-based.

Build

npx nx build baher-dotenv

Release

From the workspace root:

npm run release

Project Structure

dotenv/
  src/
    index.ts
    lib/
      core/
        constants/
        functions/
        types/
  README.md
  package.json

License

MIT License.

See LICENSE.

🇪🇬 العربية

نظرة عامة

baher-dotenv هي مكتبة موجهة لتطبيقات Node.js.

تساعدك المكتبة على تعريف متغيرات البيئة باستخدام TypeScript بشكل منظم وآمن من ناحية الأنواع، ثم تحميل هذه القيم داخل process.env.

الهدف الأساسي من المكتبة هو جعل إعدادات البيئة أكثر تنظيمًا ومركزية وتقليل الأخطاء الناتجة عن التعامل مع القيم كنصوص غير واضحة.

التثبيت

npm install baher-dotenv

طريقة الاستخدام

import { baherEnvConfig, baherLoadEnv, ENV_TYPE } from 'baher-dotenv';

const envConfig = baherEnvConfig({
  APP_NAME: {
    type: ENV_TYPE.String,
    value: 'orders-api',
  },

  APP_PORT: {
    type: ENV_TYPE.Number,
    value: 3000,
  },

  ENABLE_ELK: {
    type: ENV_TYPE.Boolean,
    value: true,
  },
});

baherLoadEnv(envConfig);

بعد تنفيذ baherLoadEnv سيتم إضافة القيم داخل process.env:

process.env.APP_NAME;   // "orders-api"
process.env.APP_PORT;   // "3000"
process.env.ENABLE_ELK; // "true"

الواجهة البرمجية

ENV_TYPE

ثابت يستخدم لتحديد نوع كل متغير بيئة.

ENV_TYPE.String
ENV_TYPE.Number
ENV_TYPE.Boolean

baherEnvConfig(config)

تستخدم لتعريف إعدادات البيئة بطريقة typed.

const envConfig = baherEnvConfig({
  APP_PORT: {
    type: ENV_TYPE.Number,
    value: 3000,
  },
});

إذا كانت قيمة value لا تطابق النوع المحدد في type، سيظهر خطأ من TypeScript.

مثال غير صحيح:

const envConfig = baherEnvConfig({
  APP_PORT: {
    type: ENV_TYPE.Number,
    value: '3000', // TypeScript error
  },
});

baherLoadEnv(config, options?)

تستخدم لتحميل القيم داخل process.env.

baherLoadEnv(envConfig);

بشكل افتراضي، إذا كانت القيمة موجودة مسبقًا داخل process.env فلن يتم استبدالها.

للسماح باستبدال القيم الموجودة:

baherLoadEnv(envConfig, {
  override: true,
});

الأنواع المدعومة

الأنواع المدعومة حاليًا:

string
number
boolean

يتم تحويل كل القيم إلى string قبل إضافتها إلى process.env، لأن متغيرات البيئة في Node.js تعتمد على النصوص.

بناء المكتبة

npx nx build baher-dotenv

إصدار المكتبة

من جذر المشروع:

npm run release

هيكل المشروع

dotenv/
  src/
    index.ts
    lib/
      core/
        constants/
        functions/
        types/
  README.md
  package.json

الترخيص

رخصة MIT.

راجع ملف LICENSE.