Package Exports

@ooneex/app-env
@ooneex/app-env/package.json

Readme

@ooneex/app-env

Environment detection and configuration management for Ooneex applications — supports development, staging, production, and testing environments.

Features

✅ 15 Environment Types - Support for local, development, staging, production, and more

✅ Boolean Flags - Quick environment checks with isProduction, isDevelopment, etc.

✅ Type-Safe - Full TypeScript support with proper type definitions

✅ Zero Dependencies - Lightweight with no external runtime dependencies

✅ Validation - Throws descriptive errors for invalid environment configurations

✅ Immutable - All properties are readonly for safety

Installation

bun add @ooneex/app-env

Usage

Basic Usage

import { AppEnv } from '@ooneex/app-env';

const env = new AppEnv('production');

if (env.isProduction) {
  console.log('Running in production mode');
}

if (env.isDevelopment || env.isLocal) {
  console.log('Debug mode enabled');
}

With Environment Variable

import { AppEnv, type EnvType } from '@ooneex/app-env';

const env = new AppEnv(process.env.APP_ENV as EnvType);

console.log(`Current environment: ${env.env}`);

Environment-Specific Configuration

import { AppEnv } from '@ooneex/app-env';

const env = new AppEnv('staging');

const config = {
  apiUrl: env.isProduction
    ? 'https://api.example.com'
    : env.isStaging
      ? 'https://staging-api.example.com'
      : 'http://localhost:3000',
  debug: env.isLocal || env.isDevelopment,
  caching: env.isProduction || env.isStaging
};

Integration with Ooneex App

import { App } from '@ooneex/app';
import { AppEnv, type EnvType } from '@ooneex/app-env';

const app = new App({
  env: new AppEnv(process.env.APP_ENV as EnvType),
  // ... other config
});

await app.run();

API Reference

Classes

`AppEnv`

Main class for environment configuration and detection.

Constructor:

new AppEnv(env: EnvType)

Parameters:

env - The environment type string

Throws: AppEnvException if env is not provided or invalid

Properties:

Property	Type	Description
`env`	`EnvType`	The current environment string
`isLocal`	`boolean`	True if environment is "local"
`isDevelopment`	`boolean`	True if environment is "development"
`isStaging`	`boolean`	True if environment is "staging"
`isTesting`	`boolean`	True if environment is "testing"
`isTest`	`boolean`	True if environment is "test"
`isQa`	`boolean`	True if environment is "qa"
`isUat`	`boolean`	True if environment is "uat"
`isIntegration`	`boolean`	True if environment is "integration"
`isPreview`	`boolean`	True if environment is "preview"
`isDemo`	`boolean`	True if environment is "demo"
`isSandbox`	`boolean`	True if environment is "sandbox"
`isBeta`	`boolean`	True if environment is "beta"
`isCanary`	`boolean`	True if environment is "canary"
`isHotfix`	`boolean`	True if environment is "hotfix"
`isProduction`	`boolean`	True if environment is "production"

Example:

const env = new AppEnv('production');

console.log(env.env);           // "production"
console.log(env.isProduction);  // true
console.log(env.isDevelopment); // false

Enums

`Environment`

Enum containing all valid environment values.

enum Environment {
  LOCAL = "local",
  DEVELOPMENT = "development",
  STAGING = "staging",
  TESTING = "testing",
  TEST = "test",
  QA = "qa",
  UAT = "uat",
  INTEGRATION = "integration",
  PREVIEW = "preview",
  DEMO = "demo",
  SANDBOX = "sandbox",
  BETA = "beta",
  CANARY = "canary",
  HOTFIX = "hotfix",
  PRODUCTION = "production",
}

Types

`EnvType`

type EnvType = `${Environment}`;
// Equivalent to: "local" | "development" | "staging" | "testing" | "test" | "qa" | "uat" | "integration" | "preview" | "demo" | "sandbox" | "beta" | "canary" | "hotfix" | "production"

`IAppEnv`

interface IAppEnv {
  readonly env: EnvType;
  readonly isLocal: boolean;
  readonly isDevelopment: boolean;
  readonly isStaging: boolean;
  readonly isTesting: boolean;
  readonly isTest: boolean;
  readonly isQa: boolean;
  readonly isUat: boolean;
  readonly isIntegration: boolean;
  readonly isPreview: boolean;
  readonly isDemo: boolean;
  readonly isSandbox: boolean;
  readonly isBeta: boolean;
  readonly isCanary: boolean;
  readonly isHotfix: boolean;
  readonly isProduction: boolean;
}

`AppEnvClassType`

type AppEnvClassType = new (env: EnvType) => IAppEnv;

Advanced Usage

Custom Environment Helper

import { AppEnv, type IAppEnv } from '@ooneex/app-env';

function isProductionLike(env: IAppEnv): boolean {
  return env.isProduction || env.isStaging || env.isUat;
}

function isDevelopmentLike(env: IAppEnv): boolean {
  return env.isLocal || env.isDevelopment || env.isTest;
}

const env = new AppEnv('staging');
console.log(isProductionLike(env)); // true

Error Handling

import { AppEnv, AppEnvException } from '@ooneex/app-env';

try {
  const env = new AppEnv('' as any);
} catch (error) {
  if (error instanceof AppEnvException) {
    console.error('Invalid environment:', error.message);
    // Handle missing or invalid environment
  }
}

Feature Flags Based on Environment

import { AppEnv } from '@ooneex/app-env';

const env = new AppEnv('beta');

const features = {
  newDashboard: env.isBeta || env.isCanary,
  experimentalApi: env.isLocal || env.isDevelopment,
  analytics: env.isProduction || env.isStaging,
  debugToolbar: !env.isProduction,
  maintenanceMode: env.isHotfix
};

Logging Configuration

import { AppEnv } from '@ooneex/app-env';

const env = new AppEnv('development');

const logConfig = {
  level: env.isProduction ? 'error' : env.isStaging ? 'warn' : 'debug',
  prettyPrint: env.isLocal || env.isDevelopment,
  includeStackTrace: !env.isProduction
};

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

Clone the repository
Install dependencies: bun install
Run tests: bun run test
Build the project: bun run build

Guidelines

Write tests for new features
Follow the existing code style
Update documentation for API changes
Ensure all tests pass before submitting PR

Made with ❤️ by the Ooneex team